N
Nanami Docs
Browse docs
Self-hosted overview
Self-hosted

Community self-hosted deployment

Run Nanami Community (Homelab) on your own infrastructure. The current supported starter topology is the single-host helper path.

Section
Self-hosted
Path
/deployment/self-hosted

Good for

Community operators preparing to run Nanami on their own infrastructure.

What you get

You understand the supported Community deployment contract, what it requires today, and how to keep it truthful.

Before you start

A Community release package or source bundle · Public app and API host planning · TLS and reverse proxy plan for browser and API traffic

This page covers the public Community (Homelab) self-hosted path.

It is not the Enterprise Self-Hosted runtime hosting and lifecycle contract. Customer-owned enterprise runtime ownership remains a planning/contact posture today, so Community runbooks must not be taught as the deploy, upgrade, or support contract for Enterprise Self-Hosted.

The current supported public starter topology is the Community single-host helper path. That topology is a release-supported starting point, not the full conceptual boundary of the Community edition.

The supported install contract is a release package or source bundle that builds the required runtime images locally by default. It must not depend on private internal GHCR packages.

Supported path

The supported public path today is the Community reference single-host helper:

  1. Obtain the current Community release package or source bundle you want to run.
  2. Copy deploy/community-single-host.env.example to deploy/community-single-host.env.
  3. Replace placeholder secrets, public hosts, and gateway endpoint/domain values.
  4. Keep COMMUNITY_IMAGE_SOURCE=build unless you intentionally supply your own public registry images.
  5. Run scripts/community_single_host.sh validate-env.
  6. Run scripts/community_single_host.sh preflight.
  7. Run scripts/community_single_host.sh up.
  8. Complete the first admin bootstrap in the product UI.
  9. Run scripts/community_single_host_smoke.sh before broader rollout.

This path is intentionally safer than manually starting each internal service one by one.

What you prepare

  • Public app URL and API URL for users.
  • A gateway domain and public origin IP for gateway traffic.
  • Real secrets instead of example placeholders.
  • TLS and reverse proxying for public browser/API surfaces.

Hardening checklist

Use the dedicated Community security checklist as the supported operator reference. The short version is:

  • use real secrets and rotate enrollment credentials,
  • terminate TLS in front of public endpoints,
  • restrict management API ingress by network controls,
  • back up Postgres regularly,
  • monitor gateway heartbeat and observed-state freshness,
  • keep internal runtime ports off the public internet.

Known limitations

  • Cross-platform managed client coverage is still expanding.
  • Some advanced policy UX remains roadmap work.

Continue

Choose the most useful continuation instead of a random article.

Community security checklistQuickstartCommon issues