N
Nanami Docs
Browse docs
Community self-hosted deployment
Run Community

Community self-hosted deployment

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

Section
Run Community
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 checkout or published release 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 source checkout or equivalent release bundle that builds the required runtime images locally by default. It must not depend on private internal GHCR packages.

The anonymous public Community distribution channel is not open yet, so external users should not expect public GitHub clone or anonymous GHCR pulls to work today. Until that channel is opened, this path requires an authorized checkout or a published release bundle from the Nanami team.

Supported path

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

  1. Obtain the current Community checkout or release 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 or explicit gateway endpoint for WireGuard 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.

Next steps

Pick the most useful next step instead of the next random article.

Community security checklistQuickstartCommon issues