Install nanobom
nanobom listens on port 8080 and keeps everything in one SQLite file. Install it with Docker
Compose, docker run, or from a release archive, then create the first administrator. Every
setting is listed in the configuration reference. To keep the
data in PostgreSQL instead, see Run on PostgreSQL.
With Docker Compose
The repository contains a ready
compose.yaml:
git clone https://github.com/AlixANNERAUD/nanobom.git
cd nanobom
docker compose up -d --wait
--wait returns once the container reports itself healthy. The file uses the published image
(ghcr.io/alixanneraud/nanobom:latest, for amd64 and arm64; the same image is on Docker Hub
as alixanneraud/nanobom) and builds it from the checkout
when it is not available. Settings come from the environment or a .env file next to
compose.yaml, for example:
# .env
NANOBOM_PUBLIC_URL=http://localhost:8080
NANOBOM_PORT=8080
compose.yaml only passes a few variables to the container. To set others, add them under
environment: in the file. Leave optional settings out rather than empty: an empty
NANOBOM_FAILURE_WEBHOOK_URL is an invalid URL, not “no webhook”.
With docker run
docker run -d --name nanobom -p 8080:8080 -v nanobom-data:/data \
-e NANOBOM_PUBLIC_URL=http://localhost:8080 \
ghcr.io/alixanneraud/nanobom:latest
The database lives in the /data volume. The image is distroless: it has no shell, so run
nanobom’s own commands with docker exec nanobom /app/nanobom …. It runs as the unprivileged
user 65532; a bind mount instead of a volume must be writable by that user.
Without containers
Each release has an archive per
architecture, nanobom-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz and
nanobom-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz, with a .sha256 checksum and build
provenance. It holds the nanobom binary and the site directory of the web interface. The
binary is built on Debian 12 and needs its glibc or a newer one.
tar -xzf nanobom-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
cd nanobom-vX.Y.Z-x86_64-unknown-linux-gnu
export NANOBOM_SITE_ROOT="$PWD/site"
export NANOBOM_DATABASE_URL="sqlite://$HOME/nanobom/nanobom.db"
mkdir -p "$HOME/nanobom"
./nanobom serve
NANOBOM_SITE_ROOT defaults to site, relative to the working directory, which only works when
nanobom starts from the extracted directory; otherwise pages load without their styles and
scripts. The default database path, /data/nanobom.db, suits the image; elsewhere, set
NANOBOM_DATABASE_URL to a file in a directory the service can write to.
As a systemd service:
# /etc/systemd/system/nanobom.service
[Unit]
Description=nanobom
After=network-online.target
Wants=network-online.target
[Service]
User=nanobom
ExecStart=/opt/nanobom/nanobom serve
Environment=NANOBOM_SITE_ROOT=/opt/nanobom/site
Environment=NANOBOM_DATABASE_URL=sqlite:///var/lib/nanobom/nanobom.db
Environment=NANOBOM_PUBLIC_URL=https://nanobom.example.org
Environment=NANOBOM_LOG_FORMAT=text
StateDirectory=nanobom
Restart=on-failure
[Install]
WantedBy=multi-user.target
Create the first administrator
Nobody can sign in to a new instance. Create an instance administrator from the command line; the password is read from standard input:
# Docker Compose
docker compose exec nanobom /app/nanobom create-administrator --username admin
# docker run
docker exec -it nanobom /app/nanobom create-administrator --username admin
# Without containers (same environment as the server, for NANOBOM_DATABASE_URL)
./nanobom create-administrator --username admin
The password is read as a plain line and shown as you type it; it must have at least
NANOBOM_PASSWORD_MINIMUM_LENGTH characters (12 by default). In scripts, pass it in
NANOBOM_ADMINISTRATOR_PASSWORD instead. --email sets an email address, which can then be used
to sign in instead of the username. All options are in the
command-line reference.
If you only use single sign-on, you can skip this step and grant administration through a claim of your identity provider instead: see Set up single sign-on.
Before opening the instance to your users
- TLS is terminated by a reverse proxy, and
NANOBOM_PUBLIC_URLis itshttpsaddress: Run behind a reverse proxy. - The proxy accepts bodies of one and a half times
NANOBOM_MAXIMUM_SBOM_SIZE(24 MiB by default, for Dependency-Track clients) and lets uploads waitNANOBOM_UPLOAD_WAIT_SECONDS. - The commands of Check the setup print what they should.
-
NANOBOM_TRUST_FORWARDED_HEADERS=true, so sign-in rate limiting sees client addresses. -
/metricsis scraped, and reachable only by your monitoring: Monitor with Prometheus. - An alert fires when the last successful run is too old, and
NANOBOM_FAILURE_WEBHOOK_URLreaches the operators: Get notified. - The database is backed up daily, and a restore was tried once: Back up, restore and upgrade.
- The instance can reach
api.osv.dev,www.cisa.govandapi.first.org, or uses mirrors, or has exploitation data turned off: Run without internet access. - Only one nanobom process uses the database (why).
A production configuration, behind a reverse proxy, with single sign-on and an alarm for failed runs:
NANOBOM_PUBLIC_URL=https://nanobom.example.org
NANOBOM_LISTEN_ADDRESS=127.0.0.1:8080
NANOBOM_TRUST_FORWARDED_HEADERS=true
NANOBOM_FAILURE_WEBHOOK_URL=https://hooks.example.org/nanobom-ops/7f3c9a
NANOBOM_OIDC_ISSUER=https://keycloak.example.org/realms/acme
NANOBOM_OIDC_CLIENT_ID=nanobom
NANOBOM_OIDC_CLIENT_SECRET=…
NANOBOM_OIDC_GROUPS_CLAIM=groups
NANOBOM_OIDC_GROUP_MAPPING="security=acme:admin;developers=acme:member"
NANOBOM_OIDC_ADMINISTRATOR_CLAIM=groups
NANOBOM_OIDC_ADMINISTRATOR_VALUE=nanobom-admins