# Deploy the core

> Run your own Nokku control plane with Docker Compose, Kubernetes or the plain binary.

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](https://github.com/nokku-sh/nokku/tree/main/core) 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 with `openssl rand -hex 32` and keep it in your secret manager. With a KMS you use that instead, see [Configure the core](/docs/self-hosting/configuration#protect-the-keys).
- **A host name**, like `nokku.example.com`, set as `NOKKU_BASE_URL`. No scheme, the core is always reached over https. Add the port only when it is not `443`. 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.

> **Tip: 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.yml` gets a real certificate for your domain. Start here for production.
- `compose.min.yml` is 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](https://github.com/nokku-sh/nokku/tree/main/core#without-a-domain).

```bash
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](https://github.com/nokku-sh/nokku/tree/main/core#client-addresses).

## Option 3: The binary

Download it from the [releases page](https://github.com/nokku-sh/nokku/releases) and run it under something that restarts it, like systemd:

```bash
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.

> **Warning: 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](https://github.com/nokku-sh/nokku/blob/main/core/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](https://github.com/nokku-sh/nokku/tree/main/core#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:

```bash
./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:

```bash
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_SENDER` to 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_SECRET` together. 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 `ssh` is untouched, and daemons reconnect by themselves.
- **Monitoring.** `/healthz` answers 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.
