This guide runs your own Nokku core. It’s a single Go binary with PostgreSQL behind it, and it is free to run. Everything else in these docs works the same against your instance.
The core README is the full reference, with every setting. This page walks you through the decisions.
What you need
- PostgreSQL, a recent version. It holds all of Nokku’s state. The core creates and updates its tables on start. The README names the oldest version that works.
- A secret for encrypting keys at rest:
NOKKU_SECRET, at least 32 characters. Generate one withopenssl rand -hex 32and keep it in your secret manager. With a KMS you use that instead, see Configure the core. - A host name, like
nokku.example.com, set asNOKKU_BASE_URL. No scheme, the core is always reached over https. Add the port only when it is not443. It is baked into sign-in links, cookies and passkeys, so pick it before you invite anyone. It has to be a name and not an IP address, because passkeys are bound to it. Any name your machines resolve works, public DNS or your internal DNS. - A reverse proxy in front that holds the TLS certificate. The core itself only speaks plain HTTP.
Why a public address helps
nokkud connects out to the core, so your servers need no open ports. If
users can reach the core too, they can reach every daemon server through the
relay, without a VPN. A core reachable only inside your network works as well,
it just can’t relay for people outside it.
Option 1: Docker Compose
The core folder of the repository has ready-made compose files. Both run the core, PostgreSQL and Caddy:
compose.prod.ymlgets a real certificate for your domain. Start here for production.compose.min.ymlis for trying it out, on this machine or on a name without a public certificate. Caddy then uses a CA of its own, which every machine has to be given. The README has the steps under Without a domain.
git clone https://github.com/nokku-sh/nokku && cd nokku/core
cp .env.prod.example .env # fill in NOKKU_BASE_URL, NOKKU_SECRET and the database password
docker compose -f compose.prod.yml up -d
Option 2: Kubernetes
There is no chart. The image runs fine in a cluster with the settings from the README: one replica, a volume or bucket for recordings, and a PostgreSQL of your own. Use the Recreate strategy, since the core keeps connections in memory and a second core waits for the first one to stop.
Let only your ingress reach the core, for example with a NetworkPolicy. The README explains why, under Client addresses.
Option 3: The binary
Download it from the releases page and run it under something that restarts it, like systemd:
export NOKKU_BASE_URL=nokku.example.com
export NOKKU_SECRET=<your secret>
export PGHOST=db.internal PGUSER=nokku PGPASSWORD=<password>
export NOKKU_TRUSTED_PROXIES=127.0.0.1 # the proxy on this machine
./nokku
The core listens on port 3000 and speaks plain HTTP. Put a reverse proxy in front. The steps below apply to every option, the compose files already do them.
What your proxy must do
nk and nokkud talk to the core over gRPC, which needs HTTP/2. Forward to
the core with h2c (HTTP/2 without TLS), and allow WebSockets for the browser
terminal. Let the proxy redirect http to https, nothing works over plain http.
The Caddyfile in
the repository is a working example, and the README has the labels for
Traefik.
The core trusts a proxy on the same machine or on a private network, like a Docker network, to tell it the client’s address. Whoever else reaches port 3000 from such an address can fake theirs, so let nothing else reach it. Next to the binary, NOKKU_TRUSTED_PROXIES=127.0.0.1 does that. Set the variable too if your proxy has a public address, or there is more than one in front. The README covers the cases under Client addresses.
First sign-in
Set NOKKU_ADMIN_EMAIL on the first start. Nokku creates the workspace and your owner account. There is no password. Get a sign-in link on the server, with the same environment the core runs with:
./nokku recover
# with Docker Compose:
docker compose -f compose.prod.yml exec nokku nokku recover
Open it, and you land signed in. Add a passkey on your profile right away, then invite your team. Until you have a passkey, the core’s log reminds you to run recover. It never writes the link itself to the log.
Lost every passkey later, and no mail goes out? Run recover again. It also works when single sign-on is required.
Connect nk and nokkud
Point both at your instance once:
nk --api https://nokku.example.com login
sudo nokkud --api https://nokku.example.com enroll
The web app shows these commands with your address filled in. If your proxy’s certificate comes from a private CA, like a company CA, give that CA to nk with --ca-file and to nokkud with NOKKUD_CA_FILE. Both keep it.
Before going live
- Email. Configure SMTP and set
NOKKU_EMAIL_SENDERto an address on your own domain. It turns on sign-in links and mailed invitations. Without it, people sign in with passkeys or your identity provider, and invitations are links you hand over yourself. - Backups. Back up PostgreSQL, the recordings storage and
NOKKU_SECRETtogether. The database holds the encrypted CA keys, the secret unlocks them. Losing the secret means losing the CA. With a KMS, its key takes the place of the secret. - Run one instance. The core keeps daemon connections, relays and half-finished sign-ins in memory. A restart ends open browser terminals and relayed sessions. A direct
sshis untouched, and daemons reconnect by themselves. - Monitoring.
/healthzanswers once the core is up. OpenTelemetry export is available. - Upgrades. Pin the image to a version and back up before you upgrade. An older version refuses to start on a database a newer one changed. The README has the deploy steps.