compose.env.example

# What a self-hoster sets for compose.yaml (engineering spec §7.11). Copy it to `.env` next to
# compose.yaml and fill it in; `.env` is never committed.
#
# Passwords: generate each one, e.g. `openssl rand -hex 32`. Hex keeps them safe inside the
# postgres:// URLs compose.yaml builds (no characters that need URL-encoding). The database
# passwords are read once, when the database volume is first created; changing them later means
# ALTER ROLE ... PASSWORD in psql as well.

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

# The postgres superuser: only the database container uses it.
KEPT_DB_SUPERUSER_PASSWORD=
# kept_owner runs migrations (the one-shot `migrate` service); never the serving process.
KEPT_DB_OWNER_PASSWORD=
# kept_app (requests), kept_auth (sign-in), kept_system (jobs and first-run setup).
KEPT_DB_APP_PASSWORD=
KEPT_DB_AUTH_PASSWORD=
KEPT_DB_SYSTEM_PASSWORD=

# The address people use to reach Kept; links and QR codes are built from it.
# Plain HTTP works, but the camera, installing the app, push and location need HTTPS (D193).
KEPT_PUBLIC_URL=http://kept.home.arpa:8080

# --- HTTPS profile (`docker compose --profile https up -d`) --------------------------------

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

# 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 on an ARM board with under 3 GB of RAM, e.g. a Pi, 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=

# --- Local AI (`docker compose --profile ollama up -d`) -------------------------------------

# Nothing to set here: compose.yaml's ollama service says which base URL to give Kept in
# Settings → AI.

# The image to run. Empty: build this checkout as kept:local.
KEPT_IMAGE=