.env.local.example

# Optional local overrides for `docker compose --profile dev up`.
#
# The stack ships sensible dev defaults in compose.yml — OpenLDAP (seeded
# users) + Mailpit (SMTP sink at http://localhost:8025). You usually don't
# need a .env.local at all.
#
# HOW COMPOSE READS THIS FILE — check this before you uncomment anything.
# The `app` service pins most settings inline in its `environment:` block, and
# inline values WIN over `env_file:`. So .env.local can only supply variables
# that block does not already name; uncommenting one it does name changes
# nothing. 23 of the 30 commented entries below are inert for that reason, so
# rather than tag each one the file is split into three parts:
#
#   PART 1 — takes effect from this file
#   PART 2 — inert from this file; edit the value in compose.yml instead
#   PART 3 — read by Compose itself, never through `env_file:`
#
# The split describes the compose dev stack only. A natively run binary loads
# `.env.local` and then `.env` on its own (godotenv, internal/options/app.go),
# so there the PART 1 and PART 2 variables apply directly. PART 3 is a Compose
# concern and has no meaning for a native run (that binary takes `PORT`).

# =======================================================================
# PART 1 — takes effect from .env.local
# =======================================================================
# None of these appear in the app service's inline `environment:` block, so
# `env_file:` supplies them. Recreate the container after editing:
#   docker compose --profile dev up -d --force-recreate app

# --- Reset identifier --------------------------------------------------
# Which identifier the reset form accepts: email (default), username, or both.
# Use `username` or `both` when several accounts share one email address
# (Active Directory does not enforce a unique mail attribute). The reset link
# is always sent to the account's registered email address, never to the typed
# value.
# RESET_IDENTIFIER_MODE=email

# --- Branding ----------------------------------------------------------
# All optional; unset => stock appearance.
# BRANDING_PRODUCT_NAME=Acme Passwords
# BRANDING_PAGE_TITLE=Acme — password self service
# BRANDING_SHOW_ATTRIBUTION=false
#
# Directory replacing the built-in assets. Same container-path caveat as the
# email templates below: the runtime image is `FROM scratch` and declares no
# volumes, so add the bind mount in compose.yml first.
# Allowed files: logo.webp, logo-dark.webp, favicon.ico, favicon-16x16.png,
# favicon-32x32.png, apple-touch-icon.png, android-chrome-192x192.png,
# android-chrome-512x512.png, mstile-150x150.png, safari-pinned-tab.svg,
# site.webmanifest, browserconfig.xml. Anything else aborts startup; max 2 MiB
# per file. styles.css and js/ are deliberately NOT replaceable.
# BRANDING_DIR=/config/branding
#
# The logo is decorative while the wordmark is shown: the alt text is then
# ignored, so screen readers do not announce the name twice. Clearing
# BRANDING_PRODUCT_NAME for a logo-only look REQUIRES the alt text, otherwise
# the header is a decorative image alone and startup aborts.
# BRANDING_LOGO_ALT=Acme Corporation

# --- Email templates & headers -----------------------------------------
# Customize the reset email. Unset => built-in defaults.
# SMTP_FROM_NAME=ACME IT
# EMAIL_REPLY_TO=helpdesk@example.com
# EMAIL_TEMPLATE_SUBJECT=[ACME] Reset your password
# Template paths must resolve INSIDE the app container. The runtime image is
# `FROM scratch` and the app service declares no `volumes:`, so a path that
# exists only on the host fails startup — add the bind mount in compose.yml
# first (see docs/development-guide.md).
# EMAIL_TEMPLATE_HTML=/config/email/reset.html   # Go template, {{.ResetLink}} etc.
# EMAIL_TEMPLATE_TEXT=/config/email/reset.txt
# Raw header injection for routing/helpdesk integrations. One var per header;
# the suffix maps _ -> - and the name is emitted in canonical (net/textproto)
# casing, so the example below sets "X-Helpdesk-Topic" however it is spelled.
# Values must not contain control characters: CR, LF, NUL, any other C0 control
# and DEL are rejected (HTAB is allowed).
# MIME-Version / Content-Type / Content-Transfer-Encoding cannot be overridden.
# SMTP_HEADER_OVERRIDE_X_HELPDESK_TOPIC=password-reset
#
# Delivery semantics:
#  * To/Cc/Bcc overrides are DISPLAY-ONLY. The SMTP envelope recipient is always
#    the reset requester, so SMTP_HEADER_OVERRIDE_BCC does NOT add a delivery
#    target — nobody extra receives the mail.
#  * Never put an address in a Bcc override that must stay hidden: it is written
#    as a real, visible Bcc: header line in the mail the reset requester gets, so
#    it adds no recipient AND leaks the address to the user.
#  * A cross-domain From-header override creates a From vs envelope MAIL FROM
#    mismatch that can break SPF/DKIM/DMARC alignment and hurt deliverability.
#
# Template fields: {{.ResetLink}} {{.Token}} {{.BaseURL}} {{.Recipient}} {{.ExpiryMinutes}}

# =======================================================================
# PART 2 — INERT from .env.local; edit compose.yml instead
# =======================================================================
# Every variable below is pinned in the app service's inline `environment:`
# block (compose.yml), which beats `env_file:`. Uncommenting one here has no
# effect on the compose stack — change the value on its line in compose.yml.
# They are kept as a reference of the names and formats, and they do apply to
# a natively run binary.

# --- Point at a different LDAP server ----------------------------------
# LDAP_SERVER=ldaps://ldap.example.com:636
# LDAP_IS_AD=true
# LDAP_BASE_DN=DC=example,DC=com
# LDAP_READONLY_USER=cn=readonly,dc=example,dc=com
# LDAP_READONLY_PASSWORD=readonly_password

# --- Dedicated reset account (recommended for prod) --------------------
# LDAP_RESET_USER=cn=password-reset,dc=example,dc=com
# LDAP_RESET_PASSWORD=reset_password

# --- Password policy ---------------------------------------------------
# MIN_LENGTH=10
# MIN_NUMBERS=1
# MIN_SYMBOLS=1
# MIN_UPPERCASE=1
# MIN_LOWERCASE=1
# PASSWORD_CAN_INCLUDE_USERNAME=false

# --- Reset feature -----------------------------------------------------
# PASSWORD_RESET_ENABLED=true
# RESET_TOKEN_EXPIRY_MINUTES=15
# RESET_RATE_LIMIT_REQUESTS=3
# RESET_RATE_LIMIT_WINDOW_MINUTES=60

# --- SMTP (Mailpit by default — override for real SMTP) ----------------
# SMTP_HOST=smtp.example.com
# SMTP_PORT=587
# SMTP_USERNAME=
# SMTP_PASSWORD=
# SMTP_FROM_ADDRESS=noreply@example.com
# APP_BASE_URL=http://localhost:3000   # must match APP_PORT — see PART 3

# =======================================================================
# PART 3 — Compose interpolation; NOT read through `env_file:`
# =======================================================================
# These are not application settings. compose.yml substitutes them into
# `ports:` (`"${APP_PORT:-3000}:3000"`, `"${MAILPIT_WEB_PORT:-8025}:8025"`),
# and Compose takes substitution values from the shell environment or from the
# `.env` file beside compose.yml — never from an `env_file:` entry. Putting
# them here only injects two unused variables into the container.
#
#   APP_PORT=3140 MAILPIT_WEB_PORT=8125 docker compose --profile dev up -d
#
# APP_BASE_URL must move with APP_PORT. It is pinned inline (PART 2) at
# http://localhost:3000, so moving only APP_PORT serves the app on the new
# port while every reset email still links to :3000, where nothing is
# listening — the mail arrives and the link is dead. Edit the APP_BASE_URL
# line in compose.yml to match the port you chose.