nano SIEM
Getting Started

Install with Docker Compose

Supported in:Self-hosted

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:

ItemRequirement
ServerOne Linux VM or physical server with 8 vCPU and 32 GB RAM. For other volumes, see Size the host
CPUAny x86-64 server CPU from about 2015 or later (it needs AVX2), or ARM64. The installer checks it
Disk1.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 systemA current 64-bit Linux that runs Docker Engine, such as Ubuntu 24.04 LTS, Debian 12 or RHEL 9. macOS works for a trial
SoftwareDocker 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
NetworkOutbound HTTPS to the image registries during install. Self-run also needs api.nano.rs. See Network access
Hostname and TLSFor 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 volumevCPURAMDisk, 365 daysDisk, 90 days
Lab or demo, enrichment off2–48 GB40 GB+40 GB+
Up to 5 GB416 GB750 GB200 GB
10–15 GB832 GB1.5 TB500 GB
25–50 GB1664 GB3–6 TB1–2 TB
50–100 GB16–3264–128 GB6–12 TB2–3 TB
About 1 TB or moreUse 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:

SettingWhat it meansDefault
NANO_PLANNED_GB_PER_DAYPlanned daily volume, in whole GBUnset
NANO_INGEST_PATHraw for logs nano parses, preshaped for OCSF that arrives already shaped from Tenzir or Criblraw (preshaped with the bundled Tenzir node)
NANO_AVG_EVENT_BYTESYour average event size, in bytes. It sets the Vector estimate1000

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 volumeWhat changes
Unset, or under 300 GB/dayNothing.
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 pathEvents per coreMeasured
raw (logs parsed by nano)1,9001,950–6,500 events/s per core across 16 benchmarked shipped OCSF parsers
preshaped (OCSF from Tenzir or Cribl)45,000Vector 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_BYTESTypical feedsVector vCPU per TB/day
About 300Firewall, flow, DNSAbout 41
1000 (default)Mixed, identity, cloud auditAbout 13
About 2000EDRAbout 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 | bash

The script:

  1. Checks prerequisites and that the Docker daemon is reachable
  2. Clones nano-rs/nano into ~/nano
  3. 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
  4. Generates random secrets, sizes ClickHouse memory and writes a 0600 .env
  5. Pulls images from ghcr.io/nano-rs and verifies their digests
  6. Runs the ClickHouse and PostgreSQL schema migrations, then starts the stack behind nginx
  7. Waits for the API to report healthy, then creates your first admin account
  8. 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 bash

Without 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.sh

The 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.lock

Self-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.

  1. Sign in to app.nano.rs. Open Deployments, then your Self-run deployment.

  2. 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.

  3. Download the first three into one directory on the server. The links are signed storage.googleapis.com URLs. 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.gz

Save 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 OK

The 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.sh

The 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 with kind, name, available and url.
  • With file=compose_bundle, compose_checksum, compose_signature, image_bundle or customer_lock, it answers with a redirect to that one file's signed link. You can then download it with curl and no JSON parser. image_bundle answers 404 when the release has no offline image bundle, which is the case for registry installs.
  • version defaults 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, .sha256 and .sha256.sig into ~/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.pem and checks that its fingerprint is a073033180edff24ddcafa20b2b2be3fbdb450da76110141f9ed8363cb135017.
  • It verifies the .sha256.sig signature on the .sha256 with openssl pkeyutl -verify -rawin, checks that the signed .sha256 is a single line naming this release's bundle, and checks the bundle's hash against it.
  • Only then, and only if ~/nano doesn't exist yet, does it log in to the registry with the same token, unpack the bundle to ~/nano and run ./install.sh with 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.

QuestionVariableWithout 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=offlineStops
The first admin's email, name and password. A blank password is generated and saved in .env as INITIAL_ADMIN_PASSWORDNANO_ADMIN_EMAIL, NANO_ADMIN_NAME, NANO_ADMIN_PASSWORDStops
Your nano URL, such as https://nano.example.comNANO_BASE_URLStops
Schema profile. Press Enter to keep ocsf; see Storage schemaNANO_SCHEMA_PROFILEocsf
Does this server reach the internet through an HTTP(S) proxy? See Corporate proxyNANO_HTTPS_PROXYNo 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_ENDPOINTSNo
Set up automatic backups? Then the destination, daily time, number to keep and the recovery key. See Automatic backups and the recovery keyNANO_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 volumeNANO_PLANNED_GB_PER_DAY, NANO_INGEST_PATHNot set
Event retention in daysNANO_RETENTION_DAYS365
Cold storage tiering to object storage: s3, s3-compatible, gcs or azure (Self-run). See storage tieringNANO_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_PROFILEUse it for
ocsf (default)New installs. Events are stored as OCSF and these docs use OCSF field paths.
ocsf+tenzirOCSF plus a bundled Tenzir node that writes OCSF straight into ClickHouse. See Direct OCSF ingest.
udmThe earlier flat field model. Kept for existing installs; see Migrating from legacy field names.

Verify it works

curl -fsS https://nano.example.com/api/health

Then 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

ServiceRole
nginxThe app's HTTP entry point (:80; HTTPS with the TLS overlay)
nano-api, nano-search, nano-jobs, nano-webAPI, search, background jobs (detections, enrichment feeds, retention) and web UI
clickhouseEvent storage: OCSF events, findings, audit, prevalence and enrichment dictionaries
clickhouse-migrateOne-shot schema migrator; runs to completion before the app services start
postgresRules, alerts, cases, users, settings and audit metadata
vectorIngest and parsing
dragonflyValkey (Redis-compatible): cache, job metadata and leases. The service keeps its name so existing installs upgrade in place.
connector-runnerPull 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

ProtocolAddressAuth
HTTP (JSON / NDJSON)http(s)://<host>/ingest through nginx, or Vector on :8080Authorization: Bearer <ingest-token>
HEChttp://<host>:8088/services/collector/event (or /services/collector/raw)Authorization: Splunk <ingest-token>
OTLP/HTTPhttp(s)://<host>/otlp/v1/{logs,traces,metrics} through nginxSource-bound ingest token. See OTLP
OTLP (raw)gRPC :4317, HTTP :4318, on 127.0.0.1None
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:

PortWhatOpen it to
80Web UI, API and ingest through nginx. With HTTPS on, it redirects to 443Your users and log senders
443Web UI, API and ingest over HTTPS, once HTTPS is onYour users and log senders
8080HTTP ingest straight to Vector (token-gated)Only your log senders, if they use it
8088HEC (token-gated)Only your log senders, if they use it
6000Vector 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:

  1. 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 key

    For example:

    install -m 0644 fullchain.pem ~/nano/config/nginx/ssl/fullchain.pem
    install -m 0600 privkey.pem ~/nano/config/nginx/ssl/privkey.pem

    Use Let's Encrypt, your own CA, or a self-signed pair for testing (./config/nginx/generate-ssl.sh; browsers will warn). Both *.pem files are gitignored.

  2. Check that ~/nano/.env has BASE_URL=https://… and NANOSIEM_DEV_MODE=false. Re-running the installer doesn't change the URL it recorded at install, so if you entered an http:// URL then, change both lines in .env.

  3. Record the TLS overlay in .env, so every later installer run, scripts/nano command 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/.env

    If .env already has a NANO_COMPOSE_OVERLAYS line, add docker-compose.tls.yml to it, separated by a space.

  4. Run the installer again. It keeps your data and settings:

    cd ~/nano && ./install.sh

    On 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.sh instead.

  5. Open port 443 in 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 :80 behind it and set your https:// 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 region auto, and an HMAC key (Cloud Storage settings, Interoperability) as the access key ID and secret. Backups have no separate GCS option. Storage tiering supports gcs directly.

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.pem

Then 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 14

Copy 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 -v

Re-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.sh

Don'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.

  1. Download the new release's bundle and verify it, exactly as in step 1 and step 2. Keep the .tar.gz, .sha256 and .sha256.sig together, for example in /srv/nano/releases/.

  2. Unpack it over your install directory. The bundle holds no .env and 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"
  3. Log in to the registry with a fresh pull credential (see Reruns, the registry and TLS).

  4. 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
  5. 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.sh

On 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
EOF

Then start nano in the same shell:

./install.sh
Reruns, the registry and TLS (Self-run)
  • From v2.0.30, a rerun needs nothing extra. The installer uses images.enterprise.customer.lock by default, logs in to the registry with the license values in .env before it pulls, in a temporary Docker configuration that leaves your ~/.docker untouched.
  • 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 .env as in Enabling HTTPS, so a plain rerun or scripts/nano upgrade keeps it. Without the overlay, nginx returns to plain HTTP.
  • Keep the extracted directory together. Don't copy install.sh out 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 upgrade with 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> with Authorization: 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

On this page