compose.env.example

# What a self-hoster sets for compose.yaml (or compose.full.yaml). `docker compose run --rm init`
# writes a `.env` with the address, the port, the image and a setup code; this file explains every
# other setting. Copy a line into `.env` (next to the Compose file) to use it; `.env` is never
# committed.

# --- Required ------------------------------------------------------------------------------

# The address people use to reach Kept; links and the QR codes on printed labels are built from
# it, so a name that won't change (http://kept.home.arpa:8080) beats an IP address. Plain HTTP
# works, but the camera, installing the app, push and location need HTTPS.
KEPT_PUBLIC_URL=

# The image to run: a released tag (`kept init` writes the one it ran as). Empty: the release
# compose.yaml names. Your own build: KEPT_IMAGE=kept:local after `docker build -t kept:local .`.
KEPT_IMAGE=

# --- Database passwords (optional) ---------------------------------------------------------

# Leave all five empty: the bootstrap service generates the four logins' passwords on the first
# start (kept-config and kept-owner volumes) and sets them in Postgres on every start, and the
# superuser gets a one-time password nobody needs (`docker compose exec db psql -U postgres`
# works without it). An install made before 1.13.0 has all five here; set, each is used as given.
# Use hex (`openssl rand -hex 32`): compose.yaml puts them inside postgres:// URLs.
KEPT_DB_SUPERUSER_PASSWORD=
KEPT_DB_OWNER_PASSWORD=
KEPT_DB_APP_PASSWORD=
KEPT_DB_AUTH_PASSWORD=
KEPT_DB_SYSTEM_PASSWORD=

# --- HTTPS profile (compose.full.yaml: `docker compose --profile https up -d`) -------------

# Caddy and Ollama are in compose.full.yaml, not compose.yaml. This line makes plain
# `docker compose` read it:
# COMPOSE_FILE=compose.full.yaml

# The domain Caddy gets a certificate for. It must resolve to this host, with ports 80 and 443
# reachable. Set KEPT_PUBLIC_URL=https://<this domain> to match.
KEPT_DOMAIN=

# --- Optional ------------------------------------------------------------------------------

# Over https Kept tells browsers to use https for this hostname for a year (HSTS), on every port.
# off, for other plain-http services on the same hostname: Kept sends max-age=0 instead,
# which clears a stored policy on the next https visit. Over http nothing is sent (default on).
KEPT_HSTS=

# How long a sign-in lasts over plain http, in whole days, 1 to 30, renewed as it is used; 7 suits a
# home network or Tailscale. Empty: 12 hours, not renewed. No effect over https (30 days).
# The cost: over plain http a sign-in cookie can be copied by anyone who can see the traffic. With
# this on, a copied one keeps working for as long as it's used, until that device signs out or your other devices are signed out.
KEPT_HTTP_SIGN_IN_DAYS=

# Other addresses this Kept answers on, such as a Tailscale name next to a LAN name, comma-separated,
# exactly as the browser shows them: http://192.0.2.20:8080,http://<machine>.<tailnet>.ts.net:8080
# No wildcards, and the same http or https as KEPT_PUBLIC_URL, or Kept stops at startup. Each signs in
# separately. Links, mail, passkeys and AI apps stay on KEPT_PUBLIC_URL. List only addresses that
# reach this Kept: a page served at one counts as Kept itself.
KEPT_EXTRA_ADDRESSES=

# Your own reverse proxy: its address as Kept sees it (on Docker's network, the proxy container's
# address, not the host's), comma-separated, ranges allowed (192.0.2.0/24).
# Only these are believed about X-Forwarded-For, so sign-in limits apply per visitor, not to the
# proxy as a whole. Empty, no proxy is believed. With compose.full.yaml's Caddy, leave it empty
# (Caddy's address is the default) or keep 172.29.72.200 in the list.
KEPT_TRUSTED_PROXIES=

# Leave both empty and Kept generates them on first boot into the kept-config volume (D193).
# To manage them yourself, set both (`docker compose run --rm migrate admin gen-key`, twice).
KEPT_SECRET_KEY=
KEPT_AUTH_SECRET=

# Host port for plain HTTP (default 8080). With the https profile you may bind it to loopback
# only, e.g. 127.0.0.1:8080.
KEPT_HTTP_PORT=8080

# e.g. smtps://user:password@mail.example.org:465. Unset, mail is only logged as due, and the
# admin status page says mail isn't configured.
KEPT_SMTP_URL=
# The From of every mail (default: Kept <no-reply@your KEPT_PUBLIC_URL host>). Most SMTP
# providers only send as an address they have verified.
KEPT_SMTP_FROM=

# info (default), debug, warn…; json (default) or pretty for reading `docker compose logs`.
KEPT_LOG_LEVEL=info
KEPT_LOG_FORMAT=json

# Preset the first-run setup code instead of reading a generated one from the logs:
# 6 characters of 0-9 and A-Z without I, L, O, U (e.g. KPT-2X9). Re-issue a lost one with
# `docker compose run --rm migrate admin setup-code` (the migrate service holds the owner login).
KEPT_SETUP_CODE=

# true or false locks sign-up open or closed; empty leaves it to the admin setting.
KEPT_SIGNUP_OPEN=

# The largest file one upload may be, in MB (default 25).
KEPT_MAX_FILE_MB=
# Photos resized at once (default: 1 under 3 GB of RAM or a container limit under 3 GB, else 2).
KEPT_IMAGE_CONCURRENCY=

# Files are stored in the kept-data volume unless KEPT_STORAGE=s3. For S3 (or RustFS, MinIO,
# Backblaze, …) set the bucket and both keys; the endpoint is empty for AWS itself, and most
# self-hosted servers need path-style URLs. KEPT_S3_PUBLIC_ENDPOINT is the address browsers reach
# the store on, when it differs from the one the server uses. Moving existing files between the
# two is a CLI migration (D186), not a switch.
KEPT_STORAGE=local
KEPT_S3_ENDPOINT=
KEPT_S3_PUBLIC_ENDPOINT=
KEPT_S3_REGION=
KEPT_S3_BUCKET=
KEPT_S3_ACCESS_KEY_ID=
KEPT_S3_SECRET_ACCESS_KEY=
KEPT_S3_FORCE_PATH_STYLE=

# Barcode lookup asks Open Food Facts and its sister sites what a scanned product is. It is off
# until an instance admin turns it on; true or false here locks it on or off instead. The
# contact is an email address sent in the User-Agent, as those sites ask of every client.
KEPT_BARCODE_LOOKUP=
KEPT_BARCODE_CONTACT=

# Web push. Leave the keys empty and Kept generates a pair on first run and keeps it in the
# database, the private key sealed; to bring your own, set both. The subject is who push
# services may contact: an https: URL or a mailto: address. Empty, it is KEPT_PUBLIC_URL when
# that is https, else mailto: the KEPT_SMTP_FROM address; with neither, push is unavailable and
# reminders go by email and in the app.
KEPT_VAPID_PUBLIC_KEY=
KEPT_VAPID_PRIVATE_KEY=
KEPT_VAPID_SUBJECT=

# Semantic search: provider embeds things with each location's AI provider (keyword search
# where none has an embeddings model); off is keyword search only. local, a model on this
# server, isn't in this build and is refused at start (D207).
KEPT_EMBEDDINGS=

# Sign in with your own OpenID Connect provider. Set the issuer (exactly as its discovery
# document states it) and the client id to turn it on. Sign-in links only to an existing or
# invited account, never by matching email. Autoprovision gives an account on first sign-in to
# the listed email domains or groups (comma-separated, exact); empty: invite only.
KEPT_OIDC_ISSUER=
KEPT_OIDC_CLIENT_ID=
KEPT_OIDC_CLIENT_SECRET=
KEPT_OIDC_NAME=
KEPT_OIDC_AUTOPROVISION_DOMAINS=
KEPT_OIDC_AUTOPROVISION_GROUPS=
KEPT_OIDC_GROUPS_CLAIM=
KEPT_OIDC_SCOPES=

# Sign in with Google. Make an OAuth client (a web application) in Google Cloud with the
# redirect URI <KEPT_PUBLIC_URL>/api/v1/auth/callback/google, and set both values. Like OIDC it
# reaches only an existing or invited account, never by matching email; nobody is let in on their
# own.
KEPT_GOOGLE_CLIENT_ID=
KEPT_GOOGLE_CLIENT_SECRET=

# --- Backups (Admin → Backups; the docs' Backups page) ----------------------------------------

# Nightly restic backups, encrypted with this password (at least 12 characters; no password, no
# backup). Each variable set here locks its field on the screen; empty leaves it to the screen.
# One target: a directory (a path inside the container: uncomment the `/backups` mounts in
# compose.yaml, the host directory owned by uid 10001, ideally on another disk), an S3 bucket, or
# SFTP (`sftp:user@host:/path`, with the key and known-hosts files mounted read-only). The nightly
# backup runs as the database owner: give the kept service KEPT_OWNER_DATABASE_URL in a
# compose.override.yaml.
KEPT_BACKUP_PASSWORD=
KEPT_BACKUP_DIR=
KEPT_BACKUP_S3_BUCKET=
KEPT_BACKUP_S3_PREFIX=
KEPT_BACKUP_S3_ENDPOINT=
KEPT_BACKUP_S3_REGION=
KEPT_BACKUP_S3_ACCESS_KEY_ID=
KEPT_BACKUP_S3_SECRET_ACCESS_KEY=
KEPT_BACKUP_S3_FORCE_PATH_STYLE=
KEPT_BACKUP_SFTP=
KEPT_BACKUP_SFTP_KEY_FILE=
KEPT_BACKUP_SFTP_KNOWN_HOSTS=
# When (HH:MM, UTC; default 02:30) and how many: the newest of each of the last N days, weeks
# and months (default 7, 4, 6).
KEPT_BACKUP_TIME=
KEPT_BACKUP_KEEP_DAILY=
KEPT_BACKUP_KEEP_WEEKLY=
KEPT_BACKUP_KEEP_MONTHLY=

# --- Upgrades -----------------------------------------------------------------------------

# With a backup target, `migrate` snapshots the database before it migrates a populated one, and
# migrates nothing if that fails. off skips the snapshot (default auto).
KEPT_UPGRADE_SNAPSHOT=
# 1 lets an older image start on a database more than one release ahead, audited. Only for a
# restore runbook; leave it empty.
KEPT_ALLOW_DOWNGRADE=
# Check GitHub for new versions: off by default and an admin setting; true or false locks it.
KEPT_UPDATE_CHECK=

# --- Observability ------------------------------------------------------------------------

# Your OpenTelemetry collector (OTLP over HTTP). Unset, no tracing code is loaded and nothing is
# sent.
OTEL_EXPORTER_OTLP_ENDPOINT=

# A bearer token (`openssl rand -hex 32`) turns on /metrics for Prometheus; empty, the path
# doesn't exist.
# KEPT_METRICS_TOKEN=

# --- Local AI (compose.full.yaml: `docker compose --profile ollama up -d`) -----------------

# Nothing to set here but COMPOSE_FILE (the HTTPS section): compose.full.yaml's ollama service
# says which base URL to give Kept in Settings → AI.