This quickstart gets you from zero to a working private network in community mode without walking through raw internal service startup commands.
The install/runtime contract below is already validated, but the anonymous public Community distribution channel is not open yet. Today you need an authorized checkout or a published release bundle from the Nanami team. Once the public channel opens, the same flow remains the supported public install path.
The supported Community path builds the required images from the current checkout by default instead of relying on private prebuilt registry artifacts.
Use the repo runtime baseline before running web checks:
nvm use
corepack enable
yarn install --frozen-lockfile
YARN_IGNORE_ENGINES=1 is emergency-only for local debugging and is not part of normal workflow.
1) Prepare the environment file
After you have the current Community checkout or release bundle:
cp deploy/community-single-host.env.example deploy/community-single-host.env
Replace the placeholder values in deploy/community-single-host.env before first boot. At minimum set real secrets, public hosts, and your gateway domain/endpoint choice. Keep COMMUNITY_IMAGE_SOURCE=build for the supported public install path.
2) Validate and preflight
scripts/community_single_host.sh validate-env
scripts/community_single_host.sh preflight
3) Start the supported community stack
scripts/community_single_host.sh up
The helper starts the required services in the supported order, bootstraps enrollment state, and keeps the public product flow consistent with the current community deploy model.
4) Complete the first admin bootstrap
Open your Nanami app URL and finish bootstrap for the first admin account.
5) Create your first group and network
In the product UI:
- Create the first network boundary for your team or environment.
- Use a non-overlapping CIDR such as
10.42.0.0/16. - Keep the first rollout small and easy to verify.
6) Enroll your first gateway and node
Use the guided gateway and node enrollment flow exposed by the running community stack instead of manually starting internal runtime services from public docs. The helper path keeps enrollment credentials scoped and auditable.
In COMMUNITY mode, change the gateway WireGuard UDP port in Dashboard -> Gateways -> gateway details (WireGuard UDP Port).
Allowed pool is fixed to 51820-54000.
If wg_listen_port is unset, default base port is 51820.
Gateways run in single-interface mode by default, so one selected UDP port is active per gateway.
Community gateway runtime uses host network mode in Docker deployments.
Forward the selected UDP port on your router/NAT to the gateway host
(example: WAN UDP 53535 -> gateway-host:53535).
If GATEWAY_HOST is DNS on Cloudflare, keep it DNS-only (proxied mode does not pass UDP).
If you use manual WireGuard configs, re-download after a gateway port change.
Manual WireGuard configs are Limited Mode: client-side AllowedIPs can be edited and are not trusted for security boundaries.
Nanami enforces network boundaries server-side on gateways.
7) Verify connectivity
In the product UI, confirm:
- network status is active,
- gateway status is healthy,
- node appears online,
- handshake timestamps and tunnel counters update.
Then run a private-service reachability check between enrolled peers.
Roll out incrementally: validate one network and one gateway path first, then scale to additional groups and regions.
Next steps
- Read Community self-hosted deployment
- Apply the Community security checklist
- Read Architecture overview