Install with Docker Compose
Install nano on a Linux server you control with Docker Compose, for Open (free) or Self-run (paid). Size the host, serve HTTPS, back up and upgrade.
The install is the same for Open (free) and Self-run (paid). With a Self-run license, you set your license values in step 4 to unlock the Self-run features and high availability.
This page installs nano on one server with Docker Compose. Events are stored in ClickHouse as OCSF events, and rules, alerts, users and settings in PostgreSQL. Both run in the Compose stack.
- Open (free, AGPL-3.0): ingest, parsing, search, detections and alerting. No account is needed. Images come from
ghcr.io/nano-rs. - Self-run (paid): everything in Open, plus cases, notebooks, pivt AI, risk analytics, SSO, playbooks, custom enrichments and high availability. You install it from the Self-run installer bundle with your license values. See Self-run.
Before you start
For about 12.5 GB/day (about 150 events per second), you need:
| Item | Requirement |
|---|---|
| Server | One Linux VM or physical server with 8 vCPU and 32 GB RAM. For other volumes, see Size the host |
| CPU | Any x86-64 server CPU from about 2015 or later (it needs AVX2), or ARM64. The installer checks it |
| Disk | 1.5 TB SSD for a year of events, or 500 GB for 90 days. Add about 100 GB for the OS and Docker. With Docker 29 and later, images go to /var/lib/containerd, so a data disk mounted only at /var/lib/docker doesn't hold them |
| Operating system | A current 64-bit Linux that runs Docker Engine, such as Ubuntu 24.04 LTS, Debian 12 or RHEL 9. macOS works for a trial |
| Software | Docker Engine 24 or later with the Compose v2 plugin (2.24.4 or later for multi-server installs), curl, OpenSSL 3 (openssl), Python 3 (python3) and git. The Open install clones with git, and the installer checks for it on Self-run too. Docker's own packages are the tested path. A distribution package, such as Ubuntu's docker.io with docker-compose-v2, works when it meets those versions |
| Network | Outbound HTTPS to the image registries during install. Self-run also needs api.nano.rs. See Network access |
| Hostname and TLS | For production, a DNS name such as nano.example.com and a certificate for it, or a load balancer that terminates TLS |
The installer checks each prerequisite up front and tells you what's missing.
Run every command as an ordinary user in the docker group, not with sudo.
Size the host
nano sizes every container from the server's CPU and RAM each time the installer runs. You choose the server size.
| Daily volume | vCPU | RAM | Disk, 365 days | Disk, 90 days |
|---|---|---|---|---|
| Lab or demo, enrichment off | 2–4 | 8 GB | 40 GB+ | 40 GB+ |
| Up to 5 GB | 4 | 16 GB | 750 GB | 200 GB |
| 10–15 GB | 8 | 32 GB | 1.5 TB | 500 GB |
| 25–50 GB | 16 | 64 GB | 3–6 TB | 1–2 TB |
| 50–100 GB | 16–32 | 64–128 GB | 6–12 TB | 2–3 TB |
| About 1 TB or more | Use Kubernetes |
A host needs at least 2 vCPU, 8 GB RAM and 40 GB free on the disk that holds Docker's data (/var/lib/docker), and 16 GB RAM with enrichment on (the default). Smaller hosts fail during install. Vector alone keeps about 17 GB of disk free, on top of its buffers and the images, so 20 GB is not enough.
These figures are a starting point. Once real data flows, watch ClickHouse CPU and memory in SIEM Health. Use SSD for the data disk, and plan for bursts of 3× your average rate. For multi-server installs, see Server sizing.
How the ratios scale:
- ClickHouse: about 5 vCPU per TB/day. A reference stack uses about 2–2.5 vCPU per TB/day. The sizes leave room for searches at peak.
- Vector: plan from events per second. Parsing costs about the same per event, whatever its size. See Plan Vector from events per second.
Plan for your daily volume
Host size alone keeps a small install small. For a large install, tell the installer how much you plan to ingest. A fresh interactive install asks. Otherwise, set these in .env and run the installer again:
| Setting | What it means | Default |
|---|---|---|
NANO_PLANNED_GB_PER_DAY | Planned daily volume, in whole GB | Unset |
NANO_INGEST_PATH | raw for logs nano parses, preshaped for OCSF that arrives already shaped from Tenzir or Cribl | raw (preshaped with the bundled Tenzir node) |
NANO_AVG_EVENT_BYTES | Your average event size, in bytes. It sets the Vector estimate | 1000 |
The planned-volume tiers change nothing unless you set a planned volume. Leave it unset, or set it to 0, and the tiers below don't apply. An existing install never gains a planned volume on upgrade. The Vector memory floor below is separate and applies either way.
| Planned volume | What changes |
|---|---|
| Unset, or under 300 GB/day | Nothing. |
| 300 GB/day and up (about the 1 TB/day tier) | ClickHouse: part limits of 2,000 / 4,000 (parts_to_delay_insert / parts_to_throw_insert), merges stop taking new work above 50% of RAM, inserts flush adaptively every 1–5 s with 256 MB buffers. Vector: sink concurrency 6, 5 s batch timeout, at least 8 GiB of memory on the raw path. Prevalence refresh every 30 minutes. |
| 3,000 GB/day and up (the 10 TB/day tier) | As above, with part limits of 5,000 / 10,000, a 1–10 s flush, Vector sink concurrency 12 and prevalence refresh every 60 minutes. |
Host size still caps every number. Sink concurrency never goes above two requests per Vector core.
When one host can't carry the planned volume, the installer says how many ingest servers of this size you need and how many Vector vCPU in total. It is a warning: nano still installs and runs. To add ingest servers, move to a multi-server install; see High availability.
Plan Vector from events per second
Parsing costs about the same per event, whatever its size. So a TB of small firewall events costs much more Vector CPU than a TB of large EDR events. Plan Vector from events per second:
events/s = GB/day × 10^9 ÷ 86,400 ÷ average event bytes
Vector vCPU = 2 (peak hour) × events/s ÷ events per core| Ingest path | Events per core | Measured |
|---|---|---|
raw (logs parsed by nano) | 1,900 | 1,950–6,500 events/s per core across 16 benchmarked shipped OCSF parsers |
preshaped (OCSF from Tenzir or Cribl) | 45,000 | Vector that only ships events does 90,000–120,000 events/s per core; planned at half for bursts |
For raw logs, that works out to:
NANO_AVG_EVENT_BYTES | Typical feeds | Vector vCPU per TB/day |
|---|---|---|
| About 300 | Firewall, flow, DNS | About 41 |
| 1000 (default) | Mixed, identity, cloud audit | About 13 |
| About 2000 | EDR | About 7 |
Pre-shaped OCSF needs about 0.5 vCPU per TB/day at 1,000 bytes per event.
Vector memory floor. The installer aims to give Vector at least 1 GiB of memory, whether or not you set a planned volume. This is best effort. When Vector's share is short, the installer takes the difference from PostgreSQL (down to 512 MiB) and then from the app services (down to their floor), never from ClickHouse. So on upgrade, an install without a planned volume can see memory move from the app or PostgreSQL to Vector. A small host, around 4 GiB of RAM, has nothing to give and can't reach 1 GiB. On such a host, pin VECTOR_MEM_LIMIT below the managed block in .env (see Sizing details and overrides), or use a larger host.
Prevalence refresh
The rare and new lists, and the host counts in the prevalence drawer, are refreshed every 10 minutes by default. With a planned volume they refresh less often, which saves CPU: every 30 minutes at about 1 TB/day and every 60 minutes at 10 TB/day and up. At those volumes, the lists can lag ingest by up to 30 or 60 minutes. Detections and searches still check a new artifact against the real-time counts, so it is still caught as rare.
To set the interval yourself, set NANO_PREVALENCE_REFRESH_MINUTES in .env and run the installer again. Unset means 10 minutes.
Retention and disk
nano keeps events for 365 days by default. Disk use is roughly:
daily volume × retention days ÷ 5 (compression) ÷ 0.75 (free space for merges)Security logs usually compress 5:1 to 10:1. Settings → Storage & Retention shows your real ratio. To keep a year for less, keep 30 to 90 days on local SSD and move older data to S3-compatible object storage with storage tiering. To shorten retention, see Event retention.
Sizing details and overrides
The installer reserves about 10% for the OS and gives ClickHouse about half of the host's memory. On an 8 vCPU, 32 GB server, ClickHouse gets about 16 GB of memory and about 4.4 vCPU, PostgreSQL about 3.5 GB and Vector about 3.3 GB. Hosts with 4 GB or less keep a 2 GB ClickHouse limit. The installer prints what it chose and writes it to a managed block at the top of .env.
To pin a value, add the same key below the managed block, for example CLICKHOUSE_MEM_LIMIT=20G, and run the installer again. An explicit value always wins.
Install
Open installs from the public nano-rs/nano repository with one command. Self-run installs from the Self-run installer bundle, with your license values. Both use the same installer, install.sh.
Open
curl -fsSL https://get.nano.rs | bashThe script:
- Checks prerequisites and that the Docker daemon is reachable
- Clones
nano-rs/nanointo~/nano - Asks for an admin account, your public base URL, the storage schema and a few settings; see What the installer asks. It reads your terminal even when piped from
curl - Generates random secrets, sizes ClickHouse memory and writes a
0600.env - Pulls images from
ghcr.io/nano-rsand verifies their digests - Runs the ClickHouse and PostgreSQL schema migrations, then starts the stack behind nginx
- Waits for the API to report healthy, then creates your first admin account
- Prints your login URL, an ingest token and sample sender commands
For unattended installs, set NANO_ADMIN_EMAIL, NANO_ADMIN_NAME, NANO_ADMIN_PASSWORD and NANO_BASE_URL before running the script. NANO_INSTALL_DIR changes the install directory, and NANO_CHECK_ONLY=1 prints the resolved edition, release and image source without installing anything.
With a terminal attached, the installer still asks every question you didn't answer with a variable (see What the installer asks). Some, such as the proxy question, have no variable for "no", so they're always asked when a terminal is there. Redirecting standard input (< /dev/null) doesn't stop them: the installer reads the terminal directly. To run with no questions at all, run it without a terminal: from CI, cron or a provisioning tool, or with setsid on Linux:
curl -fsSL https://get.nano.rs \
| NANO_ADMIN_EMAIL=secops-admin@example.com NANO_ADMIN_NAME='SecOps Admin' \
NANO_ADMIN_PASSWORD="$NANO_ADMIN_PASSWORD" NANO_BASE_URL=https://nano.example.com \
setsid -w bashWithout a terminal, each question you didn't answer takes the value in the table's last column.
To serve HTTPS, see Enabling HTTPS.
Read it first
Piping a remote script into a shell means trusting it. To inspect it before running:
curl -fsSL https://get.nano.rs -o install.sh
less install.sh
bash install.shThe container images are pinned. After pulling, the installer compares each first-party image with the sha256 digests committed in images.lock and refuses to start the stack on any mismatch. To review what will run:
curl -fsSL https://raw.githubusercontent.com/nano-rs/nano/main/images.lockSelf-run
You need your Self-run deployment in app.nano.rs and its license values. See Get your license values.
Get the bundle
There are two ways to get it: from the deployment's page in app.nano.rs, or with the license values alone, which suits scripts and AI agents. Both give the same files.
From the deployment's page. An owner or admin of your organization can do this.
-
Sign in to app.nano.rs. Open Deployments, then your Self-run deployment.
-
Under 1 · Get the installer, select Get download links. You get
nano-compose-enterprise-<version>.tar.gz, its checksum (.sha256), the checksum's signature (.sha256.sig) and an image lock.<version>is the release shown on that page. -
Download the first three into one directory on the server. The links are signed
storage.googleapis.comURLs. They last 15 minutes and work from any machine without a login, so you can copy each link and download it on the server, or give the links to your agent:curl -fLo nano-compose-enterprise-<version>.tar.gz '<link>'Treat the links as secrets until they expire. If they expire, select Refresh.
With the license values. Anyone who holds the three license values can download the bundle, with no app.nano.rs sign-in. See With the license values (scripts and agents).
nano Self-run pulls its images from the registry, at install and at upgrade, so the installer bundle is all you need. An offline image bundle, nano-<version>-enterprise.tar, exists only for air-gapped installs. Releases for registry installs don't publish one, so the page and the license API mark it as not available.
Verify and unpack the bundle, then log in to the registry
In the directory with the three downloads, set the version from your deployment's page:
VERSION=<version> # the release shown on your deployment's page
BUNDLE=nano-compose-enterprise-$VERSION.tar.gzSave nano's release signing key as release-signing-v1.pem:
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAQYUuvZPcBwXLcQgxCcZi+9S2CewrhdPy9ylKDkVjfIE=
-----END PUBLIC KEY-----Check the key's fingerprint, check the signature on the checksum, then check the bundle against the checksum:
openssl pkey -pubin -in release-signing-v1.pem -outform DER | sha256sum
openssl pkeyutl -verify -pubin -inkey release-signing-v1.pem -rawin \
-in "$BUNDLE.sha256" -sigfile "$BUNDLE.sha256.sig"
printf '%s %s\n' "$(sha256sum "$BUNDLE" | cut -d ' ' -f 1)" "$BUNDLE" | cmp - "$BUNDLE.sha256" && echo OKThe first command must print a line starting with a073033180edff24ddcafa20b2b2be3fbdb450da76110141f9ed8363cb135017. The second must print Signature Verified Successfully, and the third OK. The third rebuilds the one line the signed .sha256 must hold and compares it byte for byte, rather than running sha256sum -c, which checks whichever file the .sha256 names. If any check fails, don't install. Download the files again, and contact support if it still fails. -rawin needs OpenSSL 3.0 or later, which Ubuntu 22.04+, Debian 12 and RHEL 9 ship.
Unpack it:
tar -xzf "$BUNDLE" -C "$HOME" && mv "$HOME/nano-$VERSION" "$HOME/nano"From v2.0.30, there's no registry login to do here: the installer logs in with your license values before it pulls, in a temporary Docker configuration it removes afterwards. Your ~/.docker is never written.
v2.0.29 and earlier: get a registry credential under 4 · Registry access on the deployment's page by selecting Generate pull credential. It lasts one hour, so get it just before you install. Paste the docker login command shown with it. To get one with the license values instead, see Reruns, the registry and TLS.
Add your certificate
Skip this step if a load balancer or reverse proxy terminates TLS in front of nano, or for a lab on plain HTTP.
To have nano's own nginx serve HTTPS, copy your certificate chain and private key into the bundle now, named exactly as shown:
install -m 0644 fullchain.pem "$HOME/nano/config/nginx/ssl/fullchain.pem"
install -m 0600 privkey.pem "$HOME/nano/config/nginx/ssl/privkey.pem"The install in the next step serves plain HTTP on port 80. Once it finishes, turn HTTPS on as in Enabling HTTPS. Either way, when the installer asks for your nano URL, enter the https:// address people will open.
Run the installer with your license values
Run the installer with your license values. The deployment's page in app.nano.rs shows this command with your values filled in. Here, replace deploy_… with your deployment ID:
cd "$HOME/nano"
LICENSE_URL=https://api.nano.rs/api/license/status \
NANO_DEPLOYMENT_ID=deploy_… \
./install.shThe installer asks for the license token and doesn't echo it, so it stays out of your shell history. To pass it instead, add a LICENSE_TOKEN=… line above NANO_DEPLOYMENT_ID, as the deployment page does while it still holds the token. Pass the license values on the command like this, or let the installer ask for them. Don't create .env yourself: the installer writes it, and it reads a hand-made .env as an Open install and refuses to continue.
On v2.0.29 and earlier, also add a NANO_IMAGES_LOCK=images.enterprise.customer.lock \ line and log in to the registry first (step 2). From v2.0.30, that lock is the default.
The installer checks the server, then asks for the first admin account, your nano URL, the schema profile, a proxy, private AI endpoints, automatic backups, your planned volume, retention and storage tiering. See What the installer asks. If you set up automatic backups, read the recovery key before you answer its last question.
It writes your settings, license values and generated secrets to ~/nano/.env (mode 0600), pulls and verifies the images, starts nano, creates your admin account and prints your login URL. nano uses the license values for the daily license check-in at api.nano.rs.
If the server can't reach api.nano.rs, replace the license lines with NANO_LICENSE_MODE=offline \ and use an offline license after the install. For an install with no terminal, also set NANO_ADMIN_EMAIL, NANO_ADMIN_NAME, NANO_ADMIN_PASSWORD and NANO_BASE_URL. An unattended run stops if a license value is missing. With a terminal, the installer asks every question you didn't set; see Open for running it without one.
To review .env before nano starts, see Prepare first, then install.
The installer reads the edition from the bundle's .nano-edition marker and refuses to switch an existing install between Open and Self-run. Air-gapped installs import a signed offline license instead; see Air-gapped deployment.
With the license values (scripts and agents)
A script or AI agent that holds only LICENSE_URL, LICENSE_TOKEN and NANO_DEPLOYMENT_ID can download the bundle without signing in to app.nano.rs. Send the token as Authorization: Bearer and the deployment ID in the X-Nano-Deployment-Id header:
GET https://api.nano.rs/api/license/self-run/bundle?version=<version>&edition=enterprise- Without
file, it returns JSON with the same 15-minute signed links as the page:links[], each withkind,name,availableandurl. - With
file=compose_bundle,compose_checksum,compose_signature,image_bundleorcustomer_lock, it answers with a redirect to that one file's signed link. You can then download it withcurland no JSON parser.image_bundleanswers404when the release has no offline image bundle, which is the case for registry installs. versiondefaults to the release on the deployment's page. It can name an older release but never a newer one.
The deployment must be paid or in trial, exactly as for the page. A wrong token, a token for another deployment, or a token replaced by Regenerate license token gets 401. A canceled, unpaid or billing-locked deployment, or an ended trial, gets 402 with the reason. Each request is audited and limited per deployment.
Send the token only to api.nano.rs. The signed links need no Authorization header, so read the redirect and fetch the link without it rather than letting curl -L follow. To keep the token out of the process list, pass the header on standard input with -K -:
VERSION=<version> # the release shown on your deployment's page
BUNDLE=nano-compose-enterprise-$VERSION.tar.gz
nano_fetch() {
url=$(printf 'header = "Authorization: Bearer %s"\n' "$LICENSE_TOKEN" \
| curl -fsS -K - -H "X-Nano-Deployment-Id: $NANO_DEPLOYMENT_ID" -o /dev/null -w '%{redirect_url}' \
"https://api.nano.rs/api/license/self-run/bundle?version=$VERSION&edition=enterprise&file=$1") \
&& [ -n "$url" ] && curl -fsSL -o "$2" "$url"
}
nano_fetch compose_bundle "$BUNDLE" \
&& nano_fetch compose_checksum "$BUNDLE.sha256" \
&& nano_fetch compose_signature "$BUNDLE.sha256.sig"Then verify the signature and the checksum as in step 2 before you unpack anything.
What the install command on the page does
On releases 2.0.5 and later, the command under 3 · Install on the deployment's page is meant for a fresh server with the software above. It runs steps 1, 2 and 4 for you:
- It downloads the bundle,
.sha256and.sha256.siginto~/nano-download-<version>with your license values, as above. - It writes nano's release signing key (pinned in the command, not downloaded) to
release-signing-v1.pemand checks that its fingerprint isa073033180edff24ddcafa20b2b2be3fbdb450da76110141f9ed8363cb135017. - It verifies the
.sha256.sigsignature on the.sha256withopenssl pkeyutl -verify -rawin, checks that the signed.sha256is a single line naming this release's bundle, and checks the bundle's hash against it. - Only then, and only if
~/nanodoesn't exist yet, does it log in to the registry with the same token, unpack the bundle to~/nanoand run./install.shwith your license values. nano then serves plain HTTP on port 80.
If any step fails, it prints nano: install stopped with the reason and installs nothing. The command includes LICENSE_TOKEN only while that browser tab still holds the token. Otherwise it asks for the token once, without echoing it. Either way, it unsets LICENSE_TOKEN in your shell when it finishes or stops. The page's multi-node tab shows the prepare-then-install outline from High availability, not a one-command install.
If ~/nano already exists, from an earlier run that stopped or failed, the command stops and says how to continue: cd ~/nano && ./install.sh. That re-runs the installer for the existing install and keeps its data. Don't move or delete ~/nano to get past this stop: Docker keeps the databases in volumes, and they keep the passwords from ~/nano/.env. A new install writes a new .env with new passwords, and the databases refuse them. To start over on purpose, see Manage the stack.
To serve HTTPS from nano's own nginx, the page shows a second command under Then: serve HTTPS with your own certificate. Run it after the install. It checks that the key matches the certificate and that .env has an https:// URL, then does the steps in Enabling HTTPS.
What the installer asks
On a fresh install with a terminal, the installer asks these questions in this order, once, and records the answers in ~/nano/.env. A re-run or an upgrade doesn't ask them again. To answer one up front, set its variable on the install command.
| Question | Variable | Without a terminal |
|---|---|---|
| License: the three online values, or an offline file (Self-run, only when the values aren't on the command) | LICENSE_URL, LICENSE_TOKEN, NANO_DEPLOYMENT_ID, or NANO_LICENSE_MODE=offline | Stops |
The first admin's email, name and password. A blank password is generated and saved in .env as INITIAL_ADMIN_PASSWORD | NANO_ADMIN_EMAIL, NANO_ADMIN_NAME, NANO_ADMIN_PASSWORD | Stops |
Your nano URL, such as https://nano.example.com | NANO_BASE_URL | Stops |
Schema profile. Press Enter to keep ocsf; see Storage schema | NANO_SCHEMA_PROFILE | ocsf |
| Does this server reach the internet through an HTTP(S) proxy? See Corporate proxy | NANO_HTTPS_PROXY | No proxy |
Will nano use an AI model hosted on your own network, such as a local LLM on 10.x or 192.168.x? | NANO_ALLOW_PRIVATE_AI_ENDPOINTS | No |
| Set up automatic backups? Then the destination, daily time, number to keep and the recovery key. See Automatic backups and the recovery key | NANO_BACKUP_ENABLED and NANO_BACKUP_* | Off |
| Planned log volume in GB per day and, if you give one, whether events arrive as raw logs or pre-shaped OCSF. See Plan for your daily volume | NANO_PLANNED_GB_PER_DAY, NANO_INGEST_PATH | Not set |
| Event retention in days | NANO_RETENTION_DAYS | 365 |
Cold storage tiering to object storage: s3, s3-compatible, gcs or azure (Self-run). See storage tiering | NANO_TIERING and NANO_TIERING_* | Off |
Storage schema
The installer asks which schema to store events in. It's fixed at first install and can't be changed later.
NANO_SCHEMA_PROFILE | Use it for |
|---|---|
ocsf (default) | New installs. Events are stored as OCSF and these docs use OCSF field paths. |
ocsf+tenzir | OCSF plus a bundled Tenzir node that writes OCSF straight into ClickHouse. See Direct OCSF ingest. |
udm | The earlier flat field model. Kept for existing installs; see Migrating from legacy field names. |
Verify it works
curl -fsS https://nano.example.com/api/healthThen sign in at your nano URL with your admin account. If the password was generated, it is saved in ~/nano/.env as INITIAL_ADMIN_PASSWORD. Delete it once you've signed in.
On Self-run, also:
- On v2.0.29 and earlier, log out of the registry:
docker logout us-central1-docker.pkg.dev. Docker stores the pull credential unencrypted in~/.docker/config.json. From v2.0.30, the installer never writes the credential there. - Check the license. A licensed install shows no license banner. Within a few minutes, your deployment in app.nano.rs shows a last check-in.
Then follow Set up your first feed to onboard a log source.
What runs
| Service | Role |
|---|---|
nginx | The app's HTTP entry point (:80; HTTPS with the TLS overlay) |
nano-api, nano-search, nano-jobs, nano-web | API, search, background jobs (detections, enrichment feeds, retention) and web UI |
clickhouse | Event storage: OCSF events, findings, audit, prevalence and enrichment dictionaries |
clickhouse-migrate | One-shot schema migrator; runs to completion before the app services start |
postgres | Rules, alerts, cases, users, settings and audit metadata |
vector | Ingest and parsing |
dragonfly | Valkey (Redis-compatible): cache, job metadata and leases. The service keeps its name so existing installs upgrade in place. |
connector-runner | Pull feeds (Okta, Entra, Google Workspace, Slack and others), with the pull-feeds profile |
PostgreSQL, ClickHouse, Valkey and the app services have no published ports; they're reachable only on the internal Docker network.
Ingest endpoints
| Protocol | Address | Auth |
|---|---|---|
| HTTP (JSON / NDJSON) | http(s)://<host>/ingest through nginx, or Vector on :8080 | Authorization: Bearer <ingest-token> |
| HEC | http://<host>:8088/services/collector/event (or /services/collector/raw) | Authorization: Splunk <ingest-token> |
| OTLP/HTTP | http(s)://<host>/otlp/v1/{logs,traces,metrics} through nginx | Source-bound ingest token. See OTLP |
| OTLP (raw) | gRPC :4317, HTTP :4318, on 127.0.0.1 | None |
| Vector native | <host>:6000, every interface (from v2.0.30) | Mutual TLS: a client certificate from scripts/nano vector-client-cert. See Vector native |
A single-server Compose install serves ingest from the same server as the app. Self-run across several servers (High availability) and Kubernetes get a dedicated ingest frontend with its own hostname, so ingest load can't affect the UI and API.
Each ingest token is bound to one log source. Issue one per sender at https://<your nano URL>/ingestion/ingest-tokens, the page the installer's summary names. Use the full HEC path: Vector's HEC source doesn't serve the bare /services/collector path.
Vector native (:6000) is different from v2.0.30: it requires a client certificate on every connection, so it listens on every interface like 8080 and 8088. NANO_VECTOR_NATIVE_BIND_ADDRESS narrows it to one address. Upgrading to v2.0.30 refuses senders that have no certificate. On v2.0.29 and earlier it was plaintext, on 127.0.0.1 by default. See Vector native.
Running in production
With a http:// base URL, the installer turns on NANOSIEM_DEV_MODE so the login cookie works over plain HTTP. Don't run production on plain HTTP: without the Secure cookie flag, sessions are far more exposed.
For anything internet-facing, serve nano over HTTPS and set an https:// base URL during install. The installer then leaves dev mode off.
A single-server install isn't highly available. For Self-run across three servers, see High availability. Back up on a schedule; see Back up. Losing ENCRYPTION_KEY in .env makes every stored credential unrecoverable.
Firewall
Open these inbound TCP ports in your cloud security group or network firewall:
| Port | What | Open it to |
|---|---|---|
80 | Web UI, API and ingest through nginx. With HTTPS on, it redirects to 443 | Your users and log senders |
443 | Web UI, API and ingest over HTTPS, once HTTPS is on | Your users and log senders |
8080 | HTTP ingest straight to Vector (token-gated) | Only your log senders, if they use it |
8088 | HEC (token-gated) | Only your log senders, if they use it |
6000 | Vector native, mutual TLS (from v2.0.30) | Only your Vector senders, if they use it |
Every other port nano publishes listens on 127.0.0.1 only.
ClickHouse network allow-list
ClickHouse isn't published on the host, and no ClickHouse user accepts connections from any address. The installer limits every user to loopback and the Docker address pools that the Compose network is allocated from. Docker's defaults are 172.16.0.0/12 and 192.168.0.0/16. A subnet that a Compose overlay pins is added too. A plain docker compose up without the installer uses a built-in list: loopback plus private address space.
To let a Tenzir or Cribl writer on another host write events directly, set NANO_CLICKHOUSE_INGEST_ALLOWED_NETWORKS in .env and run the installer again. It takes a comma-separated list of IPs, CIDRs or DNS names, and admits them as the ingest user only. The bundled Tenzir container needs nothing.
Enabling HTTPS
The bundled nginx can terminate TLS with your own certificate. Install first, over plain HTTP, then turn HTTPS on:
-
Put the certificate chain (leaf first, then intermediates) and the private key, as PEM files, where nginx reads them. The key must not have a passphrase:
~/nano/config/nginx/ssl/fullchain.pem # certificate chain ~/nano/config/nginx/ssl/privkey.pem # private keyFor example:
install -m 0644 fullchain.pem ~/nano/config/nginx/ssl/fullchain.pem install -m 0600 privkey.pem ~/nano/config/nginx/ssl/privkey.pemUse Let's Encrypt, your own CA, or a self-signed pair for testing (
./config/nginx/generate-ssl.sh; browsers will warn). Both*.pemfiles are gitignored. -
Check that
~/nano/.envhasBASE_URL=https://…andNANOSIEM_DEV_MODE=false. Re-running the installer doesn't change the URL it recorded at install, so if you entered anhttp://URL then, change both lines in.env. -
Record the TLS overlay in
.env, so every later installer run,scripts/nanocommand and upgrade keeps HTTPS (v2.0.25 and later):grep -q '^NANO_COMPOSE_OVERLAYS=' ~/nano/.env || echo 'NANO_COMPOSE_OVERLAYS=docker-compose.tls.yml' >> ~/nano/.envIf
.envalready has aNANO_COMPOSE_OVERLAYSline, adddocker-compose.tls.ymlto it, separated by a space. -
Run the installer again. It keeps your data and settings:
cd ~/nano && ./install.shOn Self-run v2.0.29 and earlier, log in to the registry first (see Reruns, the registry and TLS) and run
NANO_IMAGES_LOCK=images.enterprise.customer.lock ./install.shinstead. -
Open port
443in your firewall or security group.
nginx then serves HTTPS on :443 and redirects :80 to :443. On Self-run, the deployment's page shows a command that checks the certificate and key and runs steps 1 to 4 for you.
To renew, replace the two PEM files and, in ~/nano, run docker compose -f docker-compose.opensource.yml -f docker-compose.tls.yml restart nginx.
If you already front nano with your own TLS reverse proxy or a tunnel, skip the overlay. Keep nano on
:80behind it and set yourhttps://base URL.
Retention
ClickHouse keeps events for 365 days by default, in daily partitions. Change the window, and optionally move older data to S3-compatible object storage, under Storage & Retention. Disk pressure protects the host if the local disk fills first.
Back up
Automatic backups and the recovery key
A fresh install asks Set up automatic backups? If you answer yes, it asks for a destination, a daily time and how many backups to keep, and checks the destination by writing and deleting a test object. To change these later, run scripts/nano backup-schedule --configure in ~/nano.
The destination is one of:
- A directory: a local path, or a mounted NFS or SMB share. Mount the share first.
- An S3-compatible bucket: AWS S3, Wasabi, RustFS or any other S3-compatible store. For Google Cloud Storage, choose the S3-compatible option with the endpoint
https://storage.googleapis.com, the regionauto, and an HMAC key (Cloud Storage settings, Interoperability) as the access key ID and secret. Backups have no separate GCS option. Storage tiering supportsgcsdirectly.
The installer then creates the backup keys and writes a recovery key to ~/nano/.nano-backup/keys/recovery-key.pem. It is the only key that can decrypt your backups, and nano never shows it again. The installer asks:
Have you copied the recovery key off this server? Answer y to delete it here [y/N]An unattended install (NANO_BACKUP_ENABLED=true) doesn't ask; it prints the path. Move the file off the server, then delete it there. To restore, run scripts/nano restore --key-file <recovery key> --from <backup>.
Manual backups
From v2.0.5, nano backup holds:
- PostgreSQL: alerts, cases, fired detections, rules, dashboards, parsers, users and the audit log.
- Configuration and secrets:
.env. Without it, the stored credentials can't be decrypted. - ClickHouse lookup tables: the rows behind
| lookup. - Vector native certificates (from v2.0.30):
.nano-pki, the listener CA and the sender anchors. Without it, every Vector native sender needs a new certificate after a restore.
ClickHouse event data isn't included, because a year of events is terabytes. Replicas and object storage protect it. To include it, add --include-clickhouse-data and budget space for the whole event store. IOCs and enrichment re-sync from their sources after a restore.
Create a backup key once, and keep a copy off the nano server:
sudo install -d -m 0700 -o "$USER" -g "$(id -gn)" /secure/nano-backup
cd "$HOME/nano"
scripts/nano backup-keygen --output /secure/nano-backup/operator.pemThen back up nightly, for example from cron:
cd "$HOME/nano"
scripts/nano backup --key-file /secure/nano-backup/operator.pem \
--output /mnt/backup/nano-$(date -u +%Y%m%dT%H%M%SZ) --keep 14Copy every backup off the server, and restore one into a test server now and then.
Manage the stack
Run these from the install directory (~/nano by default):
# Tail logs
docker compose -f ~/nano/docker-compose.opensource.yml logs -f
# Stop (keeps your data)
docker compose -f ~/nano/docker-compose.opensource.yml down
# Reset: deletes ALL data
docker compose -f ~/nano/docker-compose.opensource.yml down -vRe-running the installer is safe. It keeps your existing .env and secrets and restarts the stack. On Open, it also moves the install to the latest release (see Upgrade).
Don't move or delete ~/nano while its Docker volumes remain. The databases keep the passwords from its .env, and a new install in a fresh directory writes new ones that the databases refuse. To start over on purpose, run the reset above (it deletes all data), then remove ~/nano.
Upgrade
The installer runs the new schema migrations first and only then restarts the app services. Migrations are forward-only. If one fails, the app services keep running the previous version; nothing is half-applied. The API refuses to start on a schema that's behind, so always upgrade through the installer, scripts/nano upgrade or docker compose up (which runs clickhouse-migrate first).
Open
Run the installer again. It fetches the latest release, runs the migrations and restarts nano:
cd ~/nano
./install.shDon't git pull first. The published repository is regenerated for each release and can't fast-forward; the installer moves the checkout to the new release itself.
Self-run from v2.0.10 or later
nano pulls the new images from the registry. You upgrade with the new release's installer bundle, nano-compose-enterprise-<version>.tar.gz, and its .sha256 and .sha256.sig. There is no separate image bundle to download.
-
Download the new release's bundle and verify it, exactly as in step 1 and step 2. Keep the
.tar.gz,.sha256and.sha256.sigtogether, for example in/srv/nano/releases/. -
Unpack it over your install directory. The bundle holds no
.envand no data, so your settings and secrets stay as they are, and the running services don't change yet:tar -xzf /srv/nano/releases/nano-compose-enterprise-<version>.tar.gz --strip-components=1 -C "$HOME/nano" -
Log in to the registry with a fresh pull credential (see Reruns, the registry and TLS).
-
Dry-run the upgrade:
cd "$HOME/nano" scripts/nano upgrade --bundle /srv/nano/releases/nano-compose-enterprise-<version>.tar.gz \ --backup-key-file /secure/nano-backup/operator.pem --dry-run -
When every check passes, run the same command without
--dry-run.
scripts/nano upgrade checks the bundle's signature and reads the image digests, the database migrations and the upgrade requirements from inside it. Before anything changes, even in the dry run, it checks that the registry accepts your login and pulls each image by its signed digest. Then it takes a backup, runs the migrations, recreates the services that run a new image and checks that a test event becomes searchable. From v2.0.13 it also recreates every service whose configuration file changed, and prints each step as it happens. If the upgrade fails, the previous version keeps running; fix the cause and run it again with --resume. From v2.0.30, with an online license, it logs in to the registry with the license values in .env, in a temporary Docker configuration that leaves your ~/.docker untouched. On v2.0.29 and earlier, log in first and log out of the registry afterwards.
Self-run from v2.0.9 or earlier
Your install runs a release before v2.0.10, whose scripts/nano upgrade can't use the installer bundle. Upgrade to v2.0.10 by running the installer again: take a backup, download and verify the v2.0.10 bundle, unpack it over ~/nano as above, log in to the registry, and run your install command again (see Reruns, the registry and TLS). The installer keeps .env, runs the migrations and restarts nano on v2.0.10. Later upgrades follow Self-run from v2.0.10 or later.
See Upgrading.
Advanced
Prepare first, then install (Self-run)
To review or edit .env before nano starts, prepare it first:
cd "$HOME/nano"
export NANO_BASE_URL=https://nano.example.com
export NANO_ADMIN_EMAIL=secops-admin@example.com NANO_ADMIN_NAME='SecOps Admin'
printf 'Admin password: '; stty -echo; read -r NANO_ADMIN_PASSWORD; stty echo; echo; export NANO_ADMIN_PASSWORD
NANO_PREPARE_ONLY=1 ./install.shOn v2.0.29 and earlier, also export NANO_IMAGES_LOCK=images.enterprise.customer.lock. To serve HTTPS from nano's nginx, follow Enabling HTTPS after nano is running.
The installer writes ~/nano/.env and stops. Add the three license values to the .env it wrote:
cat >> "$HOME/nano/.env" <<'EOF'
LICENSE_URL=https://api.nano.rs/api/license/status
LICENSE_TOKEN=paste-your-license-token
NANO_DEPLOYMENT_ID=paste-your-deployment-id
EOFThen start nano in the same shell:
./install.shReruns, the registry and TLS (Self-run)
- From v2.0.30, a rerun needs nothing extra. The installer uses
images.enterprise.customer.lockby default, logs in to the registry with the license values in.envbefore it pulls, in a temporary Docker configuration that leaves your~/.dockeruntouched. - On v2.0.29 and earlier, every installer run needs a fresh registry login and
NANO_IMAGES_LOCK=images.enterprise.customer.lock. - If nano serves TLS, record the overlay in
.envas in Enabling HTTPS, so a plain rerun orscripts/nano upgradekeeps it. Without the overlay, nginx returns to plain HTTP. - Keep the extracted directory together. Don't copy
install.shout of it. - To renew the certificate, replace both files and run
docker compose -f docker-compose.opensource.yml -f docker-compose.tls.yml restart nginx. - With an
http://base URL, the installer turns on dev mode so login cookies work without TLS. Use it only in a lab. - From v2.0.30,
scripts/nano upgradewith an online license logs in to the registry itself, like the installer. On v2.0.29 and earlier, and with an offline license, it needs a registry login before it runs. To log in from a script, request a credential with your license token.GET https://api.nano.rs/api/license/self-run/registry-token?deploymentId=<id>withAuthorization: Bearer <LICENSE_TOKEN>returns a pull credential that lasts one hour:
. <(grep -E '^(LICENSE_TOKEN|NANO_DEPLOYMENT_ID)=' "$HOME/nano/.env")
( umask 077; printf 'Authorization: Bearer %s\n' "$LICENSE_TOKEN" > "$HOME/.nano-license-header" )
curl -fsS -H @"$HOME/.nano-license-header" \
"https://api.nano.rs/api/license/self-run/registry-token?deploymentId=$NANO_DEPLOYMENT_ID" \
| python3 -c 'import json,sys; print(json.load(sys.stdin)["password"])' \
| docker login -u oauth2accesstoken --password-stdin us-central1-docker.pkg.dev
rm -f "$HOME/.nano-license-header"curl reads the token from a header file, so it never appears in the process list.
Troubleshoot
Need help with these checks? Contact support with your deployment ID (Self-run), the request ID and the time, with timezone. For license problems, see Self-run troubleshooting.
The installer stops at a prerequisite check
Check Docker Engine, Compose v2, curl, openssl (OpenSSL 3), python3 and git. Correct the missing prerequisite and run the installer again: cd ~/nano && ./install.sh.
The page's install command says ~/nano already exists
An earlier run unpacked the bundle and then stopped. Continue that install with cd ~/nano && ./install.sh; it keeps the data. Don't move or delete ~/nano: see What the install command on the page does.
nano doesn't answer on HTTPS
Check that ~/nano/config/nginx/ssl/fullchain.pem and privkey.pem exist, that the key has no passphrase, that .env lists docker-compose.tls.yml in NANO_COMPOSE_OVERLAYS, and that port 443 is open. See Enabling HTTPS. The nginx log says which file it couldn't load: docker compose -f ~/nano/docker-compose.opensource.yml -f ~/nano/docker-compose.tls.yml logs nginx.
The installer refuses the CPU
ClickHouse needs a CPU with AVX2 on x86-64, which every mainstream server CPU since about 2015 has. On a VM, the hypervisor may hide it: on Proxmox, set the CPU type to host or x86-64-v3. ARM64 servers don't need it.
The image pull fails with 401 or 403
From v2.0.30, the installer gets a fresh credential on every run with the license values in .env. Check that LICENSE_TOKEN is current (Regenerate license token replaces the old one) and that the server reaches api.nano.rs, then run ./install.sh again. From v2.0.30, scripts/nano upgrade does the same. On v2.0.29 and earlier, the registry credential expired: get a new one, paste its docker login command and run the command again.
The upgrade dry run reports C05
In nano 2.0.x, the dry run can report C05 licence state is missing or expired on an online-licensed install. Contact support before you upgrade, and don't bypass the check.
Events have no geolocation or ASN
ClickHouse has less than 6 GB of memory, so the IP dictionary couldn't load. Use a server with 16 GB of RAM or more, or pin CLICKHOUSE_MEM_LIMIT=6G or higher below the managed block in .env and run the installer again. See Size the host.
Ingest slows down or senders see backpressure
ClickHouse is short of memory or CPU for the volume. A 2 GB ClickHouse sustains only about 200 events per second. Move to a larger host and run the installer again, or pin a higher CLICKHOUSE_MEM_LIMIT.
A sender cannot reach HEC
Use http://<host>:8088/services/collector/event and confirm that the sender can reach port 8088. The bare /services/collector path is not served. See HEC troubleshooting.
What's next
Set Up Your First Feed
Add a log source, publish its parser, issue a source-bound ingest token, send events and verify they arrive parsed as OCSF.
Install on Kubernetes (Helm)
Install nano Self-run on your own Kubernetes cluster with the nano Helm chart, then size it, make it highly available and upgrade it.