Skip to content
Nokku LogoNokku
GuidesLearn the concepts

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

Last updated on

The core is configured with environment variables. The complete, current list is in the core README, and it matches the version you run. The settings that matter for security, like key management, are in its SECURITY.md. This page covers the choices behind them.

Required

  • NOKKU_SECRET, at least 32 characters, or a KMS instead. See 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.

Choices to make

TopicOptionsWhat to consider
Reverse proxyAny proxy that speaks h2c to the coreTrusted as it is on the same machine or a private network. Set NOKKU_TRUSTED_PROXIES for anything else
File storageA local folder, or S3-compatible storageHolds session recordings. They are encrypted before they are stored, either way
EmailAny SMTP relayTurns on sign-in links and mailed invitations. Without it, passkeys and SSO are the ways in
Key protectionNOKKU_SECRET, or a KMSA KMS (HashiCorp Vault or Scaleway) holds the key that unlocks everything, instead of the secret
Sign-inPasskeys, email links, OIDCProviders are set up in the web app. Google and Microsoft can also be seeded from the environment
TelemetryOpenTelemetry, off by defaultTraces, metrics and request logs go to your own collector. The log itself only has warnings and errors
Operator detailsOff by defaultYour 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 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.

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