# Configure the core

> The decisions that shape a self-hosted core, and where the full list of settings lives.

The core is configured with environment variables. The complete, current list is in the [core README](https://github.com/nokku-sh/nokku/tree/main/core#configuration), and it matches the version you run. The settings that matter for security, like key management, are in its [SECURITY.md](https://github.com/nokku-sh/nokku/blob/main/core/SECURITY.md#running-nokku-securely). This page covers the choices behind them.

## Required

- `NOKKU_SECRET`, at least 32 characters, or a KMS instead. See [Protect the keys](#protect-the-keys).
- A PostgreSQL connection, through the standard `PGHOST`, `PGUSER`, `PGPASSWORD` and related variables.
- `NOKKU_BASE_URL`, the host name people and machines reach the core at. See [Deploy the core](/docs/self-hosting/deploy#what-you-need).

## Choices to make

| Topic            | Options                                  | What to consider                                                                                         |
| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Reverse proxy    | Any proxy that speaks h2c to the core    | Trusted as it is on the same machine or a private network. Set `NOKKU_TRUSTED_PROXIES` for anything else |
| File storage     | A local folder, or S3-compatible storage | Holds session recordings. They are encrypted before they are stored, either way                          |
| Email            | Any SMTP relay                           | Turns on sign-in links and mailed invitations. Without it, passkeys and SSO are the ways in              |
| Key protection   | `NOKKU_SECRET`, or a KMS                 | A KMS (HashiCorp Vault or Scaleway) holds the key that unlocks everything, instead of the secret         |
| Sign-in          | Passkeys, email links, OIDC              | Providers are set up in the web app. Google and Microsoft can also be seeded from the environment        |
| Telemetry        | OpenTelemetry, off by default            | Traces, metrics and request logs go to your own collector. The log itself only has warnings and errors   |
| Operator details | Off by default                           | Your company name, support address and legal links in the web app and in emails                          |

## Protect the keys

Everything the core encrypts at rest, like the CA's private keys and SSO client secrets, is unlocked by one key:

- **`NOKKU_SECRET`** is the simple way. Keep it in your secret manager, and back it up together with the database. One is useless without the other.
- **A KMS** keeps that key out of the environment. Set `KMS_URI` instead of the secret. The core needs the KMS to start, not to sign, so check it before you deploy.

Keys change only through `nokku rotate-secrets`, run while the core is stopped. It moves you to a new secret or to a KMS, and re-encrypts the secrets in the database. [core/SECURITY.md](https://github.com/nokku-sh/nokku/blob/main/core/SECURITY.md#rotating-the-secret) has the steps, the Vault policy and how to keep a Vault token alive.

A rotation does not un-leak anything. If the old secret and a database backup both got out, also [roll over the CA](/docs/security/certificate-authority#roll-over-the-ca).

## The first owner

A self-hosted core serves one workspace. It is created on the first start, together with the owner from `NOKKU_ADMIN_EMAIL`. The owner signs in with the link from `nokku recover`, see [First sign-in](/docs/self-hosting/deploy#first-sign-in). The same command is the way back in for an owner who lost every passkey, so keep shell access to the core for people you trust with the workspace.

## Background jobs

The core cleans up after itself: it prunes expired sessions and sign-in links, ends grants and requests on time, and applies retention to audit events and recordings. Nothing to configure.
