Install

Quick install

With a domain (Let's Encrypt)

Verify before you run it

The one-liner pipes a script into root's shell. Every release also ships a SHA256SUMS file, so the safer form is download, verify, then run.

Requirements

• x86_64 or arm64 Linux with a root Docker daemon — rootless Docker is not supported
• Ports 80 and 443 free for Traefik
• 2 GB RAM minimum, 4 GB+ if you build images on the host
• 5 GB free disk on both the config directory and the Docker root

What the installer does

1. Installs Docker if needed and initializes Swarm
2. Runs a preflight: ports 80/443, disk, memory, rootless Docker, and your domain's DNS record against this host's public IP
3. Creates the two platform overlays — nixploy-network (Traefik-facing, joined only by services that have a domain) and nixploy-internal (panel ↔ Postgres, never any tenant container)
4. Writes secrets under /etc/nixploy (mode 600) and generates a one-time setup token
5. Pulls (or builds) the Nixploy image from GHCR
6. Starts Postgres + Traefik + the panel, then waits for GET /api/ready through Traefik on loopback
7. Prints the setup URL with the token, and the firewall one-liner for this host

Useful overrides

• NIXPLOY_VERSION / NIXPLOY_IMAGE — pin or override the app image
• NIXPLOY_PORT — opt-in extra host port for plain-HTTP access (unset = Traefik only)
• NIXPLOY_CONFIG_DIR — config root (default /etc/nixploy)
• NIXPLOY_MEMORY_LIMIT — memory ceiling of the panel service (default 2g)
• TZ — timezone every cron runs in (default UTC)
• LOG_LEVEL / LOG_FORMAT=json — panel logging
• TRUSTED_PROXIES — set to 1 by the installer so the real client IP is read from X-Forwarded-For behind Traefik. Without it every client IP reads as unknown and the IP-based rate limits collapse into one shared bucket
• NIXPLOY_GITHUB_TOKEN — private-repo install/update
• NIXPLOY_SKIP_DOCKER_INSTALL=1 — use an existing Docker daemon

Deadlines and retention

• NIXPLOY_COMMAND_TIMEOUT_MS — every local shell/Docker command (default 30 minutes); NIXPLOY_REMOTE_COMMAND_TIMEOUT_MS is the SSH equivalent
• NIXPLOY_DEPLOY_TIMEOUT_MS — per-deployment deadline (default 60 minutes); the job is cancelled and the row fails
• NIXPLOY_CONVERGENCE_TIMEOUT_MS — how long a rollout may take to produce one running task (default 180 seconds)
• NIXPLOY_HOOK_TIMEOUT_MS — pre/post-deploy hooks and image jobs (default 10 minutes)
• NIXPLOY_METRICS_RETENTION_HOURS — metrics history window (default 48, maximum 720; 12 on the lite profile)
• NIXPLOY_RUNTIME_LOGS, NIXPLOY_RUNTIME_LOG_RETENTION_DAYS, NIXPLOY_RUNTIME_LOG_MAX_MB_PER_SERVICE — the runtime log harvester and what it keeps per service (on, 7 days, 256 MB; off / 2 days / 64 MB on the lite profile)
• NIXPLOY_REMEDIATION — 0 stops the rules that propose a rollback after a failed rollout or a restart loop
• NIXPLOY_AUDIT_RETENTION_DAYS — audit log retention (default 365, 0 keeps rows forever)
• NIXPLOY_DEPLOY_CONCURRENCY — deploy jobs built in parallel per target server (default 1)

Footprint, and the lite profile

The control plane is three containers: the panel, Postgres and Traefik. On the production box they measure 424, 51, 28 MiB, read on 20 Sep 2026 — reproduce it with docker stats --no-stream on any install. CI measures the panel a second way: the end-to-end job runs the full golden path (setup, two deploys including a build from source, a UI walk) against the release image and reads the container's resident memory afterwards, which has landed between 419 and 434 MiB. A run over the 768 MiB budget fails the build, so a change that doubles the panel's memory is caught before it reaches anyone's 4 GB box.

install.sh --lite (or NIXPLOY_LITE=1, which update.sh forwards) is the profile for a 1–2 GB box. It does not turn features off behind your back: it changes the defaults of five knobs, and each of them still wins when you set it, so a lite install that wants runtime logs back sets one variable and keeps the rest lean.

• Runtime log harvesting off (NIXPLOY_RUNTIME_LOGS=1 brings it back); its history caps drop to 2 days / 64 MB per service
• Metrics sampled every 2 minutes instead of 30 seconds, kept 12 hours instead of 48
• Uptime probes every 2 minutes instead of 30 seconds
• Four SSH channels per managed server instead of eight
• NIXPLOY_MEMORY_LIMIT and NIXPLOY_WORKER_MEMORY default to 1g instead of 2g

Split worker (optional)

By default Nixploy is one process: UI, API, websockets, the deploy queue and every cron share a memory limit. --split-worker moves the background half into its own Swarm service, nixploy-worker.

• nixploy runs with NIXPLOY_ROLE=panel — UI, tRPC, REST, MCP, websockets; it still enqueues deploys and writes per-domain Traefik YAML
• nixploy-worker runs with NIXPLOY_ROLE=worker — the deploy claim loop, boot recovery, every cron, and /api/health, /api/ready, /api/version
• Updating the panel stops interrupting builds: a panel restart closes sockets in milliseconds while the worker keeps building
• Separate memory ceilings (NIXPLOY_MEMORY_LIMIT and NIXPLOY_WORKER_MEMORY), so a 2 GB build cannot OOM the UI
• The two halves coordinate over Postgres LISTEN/NOTIFY — no broker, no extra port, no schema change

Health endpoints

• GET /api/health — liveness, no dependencies
• GET /api/ready — per-check readiness (database, Docker socket, migration state, deploy queue, Traefik, platform alerts); 503 with the failing checks listed
• GET /api/version — version, commit, Node and Next versions for nixploy doctor and support

Air-gapped install

Update

• Settings → Platform → Updates shows the GitHub release notes for the image the instance tracks, not just a digest
• Update to a specific release: only the tag changes, never the registry or repository the instance already trusts
• pinnedVersion is a ceiling for automatic updates — the checker logs “held back” instead of rolling past it
• Downgrades are refused unless you allow them explicitly: migrations are forward-only, so restore the pre-update dump first

Uninstall