Model Hotel is configured through environment variables (startup-only) and runtime database settings (changeable without restart).

A normal deployment needs two secrets in .env: MASTER_KEY and POSTGRES_PASSWORD. Everything else on this page has a working default.

Reach for the rest only when something specific applies to you: a reverse proxy in front (TRUSTED_PROXIES, COOKIE_SECURE), a self-hosted LLM server on a private address (ALLOWED_PROVIDER_HOSTS), passkey login (WEBAUTHN_RP_ID), or a log collector (LOG_FORMAT, METRICS_TOKEN, OTEL_EXPORTER_OTLP_ENDPOINT).

Runtime behaviour (timeouts, retries, rate limits, discovery, backups) is changed in the Settings UI, not in .env: those live in the database and take effect without a restart.

Environment variables are read once at server startup and cannot be changed at runtime. The application reads the process environment, plus a .env file in its working directory (via godotenv; variables already set win). The Docker image excludes .env files, so in a container only the service's environment: list counts (see above); the .env file is loaded directly only when the binary runs outside Docker.

The following provider hosts are always allowed as provider base_url values, regardless of ALLOWED_PROVIDER_HOSTS:

• api.openai.com
• api.nano-gpt.com
• api.z.ai
• api.kimi.com
• kimi.com
• api.minimax.io
• minimax.io
• api.deepseek.com
• api.anthropic.com
• ollama.com
• opencode.ai
• api.x.ai
• generativelanguage.googleapis.com
• aiplatform.googleapis.com
• api.cohere.com
• api.cohere.ai
• openrouter.ai
• api.neuralwatt.com
• neuralwatt.com

Subdomains of the vendor domains are allowed too, so a regional or tenant-specific endpoint needs no allowlist entry: .nano-gpt.com, .z.ai, .kimi.com, .minimax.io, .deepseek.com, .anthropic.com, .ollama.com, .opencode.ai, .x.ai, .cohere.com, .cohere.ai, .openrouter.ai, .neuralwatt.com.

These correspond to most of the vendor hosts recognised by detectByHost in internal/provider/discovery.go, but not all: Azure (*.openai.azure.com, *.services.ai.azure.com), Bedrock (bedrock-mantle.<region>.api.aws) and regional Vertex or Gemini hosts (e.g. us-central1-aiplatform.googleapis.com) are detected yet not always allowed, so once ALLOWED_PROVIDER_HOSTS is set they must be listed in it.

At dial time the SafeDialer skips its IP checks for the exact hostnames in the list above and for every ALLOWED_PROVIDER_HOSTS entry. Hosts accepted only through a subdomain suffix are still resolved and IP-checked on every connection.

• MASTER_KEY is never used directly as an AES key. It is fed through Argon2id key derivation (per-provider random salt in v2) to produce the 256-bit AES key. See Security for details.
• ADMIN_TOKEN is stored as a SHA-256 hash. Legacy plaintext tokens are automatically migrated to hashed format on first validation.
• RATE_LIMIT_ENABLED is a hard kill-switch - when false, the rate-limiting middleware is always mounted but becomes a complete pass-through (no buckets, no headers, no 429s). The DB setting rate_limit_enabled has no effect when the env var is false.
• SSRF protection (server-side request forgery: tricking the server into calling an address it should not) has two layers. Provider URL validation runs when a provider is saved; the SafeDialer re-checks the resolved IP on every outbound connection (except to the exact built-in hostnames and ALLOWED_PROVIDER_HOSTS entries, which it trusts by name), so a hostname that later resolves to a private address is still blocked.
• TRUSTED_PROXIES is about inbound metadata (which reverse proxies may set X-Forwarded-For). KNOWN_PROXIES is about outbound connections (which private CIDRs the SafeDialer may dial). They point in opposite directions.
• ALLOWED_PROVIDER_HOSTS names specific hostnames and bypasses both SSRF layers. KNOWN_PROXIES names CIDR ranges and bypasses only the SafeDialer's private-IP block, so provider URL validation still applies and still refuses a private address. A provider on a private address therefore always needs an ALLOWED_PROVIDER_HOSTS entry; KNOWN_PROXIES alone cannot get it created. Built-in provider hosts need neither. Remember that setting ALLOWED_PROVIDER_HOSTS turns it into a strict allowlist for every non-built-in host.
• Self-hosted providers (Ollama, LM Studio, KoboldCPP, LocalAI, SGLang, TabbyAPI) run on an address you choose and are not in the built-in host allowlist; add them to ALLOWED_PROVIDER_HOSTS. The same URL validation applies to the probe that confirms the server type when the provider is added: a host the validation rejects (a private address with ALLOWED_PROVIDER_HOSTS unset, for instance) cannot be added at all.
• Neither variable applies to the admin-configured endpoints (OIDC issuer, apprise-api, Front Desk members). Those go through a separate guard that already allows private and loopback addresses and blocks only link-local/metadata ones, so an internal IdP needs no allowlisting at all. It has no env vars; see netguard.
• WEBAUTHN_RP_ID is empty by default, meaning passkey login is disabled. Set it to your domain to enable FIDO2/WebAuthn passkey authentication. WEBAUTHN_RP_ORIGINS falls back to CORS_ORIGINS and then to http://localhost:<port>.
• DATABASE_MAX_CONNS and DATABASE_MIN_CONNS are each clamped to the range 1–1000, independently of one another.
• CORS_ORIGINS explicitly rejects * wildcard - it is incompatible with credentials=true (CORS spec forbids it) and would silently break auth.

These settings are stored in the settings table and can be changed at runtime via the Settings UI or the PUT /api/settings endpoint - no restart required. Changes take effect immediately (within 30 seconds of cache TTL at most, or instantly via the subscription notification system).

All 62 writable keys, grouped by the area they govern. Keys owned by another page get a one-line row here and their full treatment there. This table is also the reference for what a Reset to Defaults restores.

GET /api/settings also returns read-only status keys that no PUT may write: app_version, app_commit, discovery_claim_window_days, and the three log_export_* flags the Observability panel reflects.

The TTFT probe holds the client connection open without sending any bytes until the upstream produces its first token (up to ttft_timeout). If Model Hotel runs behind a reverse proxy, load balancer, or CDN, that intermediary's idle-read timeout can close the silent connection before the first token arrives, and Model Hotel only sees its inbound connection drop.

To avoid this, either:

• raise the proxy's read timeout above ttft_timeout (nginx: proxy_read_timeout 600s;) and disable response buffering for streaming (nginx: proxy_buffering off;), or
• set ttft_timeout below the proxy's read timeout, so Model Hotel's own probe fires first and fails over to the next provider while the connection is still alive.

A request cut off this way is logged as a provider_timeout (502) whose message names the likely reverse-proxy cause, and the stalling provider's circuit breaker records the failure, so repeated stalls open the breaker and subsequent requests skip that provider.

When PWNED_PASSWORD_CHECK_ENABLED is true (the default) and the runtime pwned_password_check_enabled toggle is on, every new dashboard password (set at user creation, admin reset, or self-service change) is checked against the Have I Been Pwned Pwned Passwords corpus before it is accepted. If the password appears in a known breach, the change is rejected and the user is asked to pick a different one.

The lookup uses k-anonymity: the password is hashed with SHA-1, only the first 5 hex characters of the hash are sent to the range API, and the full password never leaves the box. The API returns every suffix sharing that prefix along with a breach count, and Model Hotel matches the remaining suffix locally.

The check is fail-open: if the range endpoint is unreachable, times out, or errors, the password change is allowed rather than blocked - it only ever adds a rejection, never a lock-out. The 8-character length minimum is enforced first and short-circuits the lookup.

For air-gapped or egress-restricted deployments, point PWNED_PASSWORD_API_URL at a local mirror that speaks the same GET /range/{prefix} contract. IncogniPwn serves the full Pwned Passwords corpus (~80 GB) from a downloader + API pair. Add it to your docker-compose.yml:

services:
  hibp-downloader:
    # One-shot: downloads the Pwned Passwords corpus into the shared volume.
    # Re-run periodically to refresh. Expect ~80 GB and a long first run.
    image: ghcr.io/millaguie/incognipwn-downloader:latest
    volumes:
      - hibp-data:/data
    restart: "no"

  hibp-api:
    # Serves GET /range/{prefix} on port 8000 from the downloaded corpus.
    image: ghcr.io/millaguie/incognipwn-api:latest
    volumes:
      - hibp-data:/data
    expose:
      - "8000"
    restart: unless-stopped

  app:
    # ... your existing Model Hotel service ...
    environment:
      PWNED_PASSWORD_API_URL: http://hibp-api:8000
    depends_on:
      - hibp-api

volumes:
  hibp-data:

The mirror only needs to be reachable from the app container: do not expose it publicly. Because the check fails open, Model Hotel keeps accepting password changes even while the downloader is still populating the corpus.

All database settings can be reset to their Go-side defaults via the Reset to Defaults feature in the Settings UI:

• Global reset (header icon): Type "RESET" to confirm. Deletes all settings from the database.
• Section reset (icon left of collapse toggle): Confirms via dialog. Resets only the settings in that section.
• Per-setting reset (inline icon after label): Resets a single setting. No confirm dialog.

Reset works by deleting the row from the settings table. The Go code then falls through to its hardcoded default value, which is the Default column of the Settings Reference above. The returned settings map reflects the post-reset state.

The rate limiting system has two layers, both using token buckets (backed by golang.org/x/time/rate):

Per-IP rate limiting (DoS protection, always-on when enabled):

• Applied before authentication, before the per-key limiter
• rate_limit_ip_rps controls the per-IP refill rate (default 30)
• rate_limit_ip_burst controls the per-IP maximum burst size (default 60)
• rate_limit_ip_enabled toggles this layer at runtime (requires RATE_LIMIT_ENABLED=true)
• Independent bucket per client IP address

Per-virtual-key rate limiting (usage control):

• Each key gets its own independent bucket
• rate_limit_rps controls the refill rate (tokens per second, default 10)
• rate_limit_burst controls the maximum bucket size (default 20)
• Setting rate_limit_rps=0 makes every bucket unlimited (no per-key rate limiting)
• A separate optional token rate limit caps tokens/minute and rejects over-budget requests with 429. It has a global default setting (rate_limit_tpm, 0 = no cap, API-only, with no Settings-UI control) plus a per-key override on the virtual_keys row; a key's null falls back to the global default. See Virtual Keys.

Shared settings:

• rate_limit_max_wait_ms (default 200) - maximum time a request waits in the rate-limiter queue before being rejected with 429. Applies to both per-IP and per-key limiters.
• The RATE_LIMIT_ENABLED environment variable is a hard kill-switch - when false, both layers are always mounted but become a complete pass-through (no buckets, no headers, no 429s)
• When rate limiting is re-enabled after being disabled, all existing buckets are reset to ensure fresh state
• Unused buckets are cleaned up by a periodic cleanup task that runs every 5 minutes and removes entries that have been idle for more than 10 minutes

When a request is rate-limited, the response includes:

• Retry-After: <seconds> - When the client can retry
• X-RateLimit-Limit: <rate> - The refill rate
• X-RateLimit-Remaining: <tokens> - Remaining tokens in the bucket
• X-RateLimit-Burst: <burst> - The burst capacity
• X-RateLimit-Scope: <ip|key> - Indicates whether the rate limit applies to ip (per-IP) or key (per-virtual-key)

User preferences are stored in localStorage (client-side only, never sent to the server):

The Settings page has 10 collapsible sections. On a managed fleet member the instance-local sections (Authentication, Appearance, Observability, and the local half of Alerts) come first, followed by the managed banner and the fleet-synced sections. The primary shows an amber banner at the same boundary noting that the sections above stay per-member (except the password policy, the sign-in email allowlists and the alert event routing, which are synced) while everything below is pushed to the fleet on the next config sync.

• Passkeys: WebAuthn/FIDO2 credential management: register new passkeys, rename and delete existing ones. Registration is available only when WEBAUTHN_RP_ID is configured (see Security).
• Two-Factor (TOTP): Authenticator-app 2FA (RFC 6238) for admin login. Enabled at runtime from Settings (scan a QR code, confirm a 6-digit code, save the one-time recovery codes); no environment variable is required. When enabled, the raw admin token alone no longer authenticates and must be combined with a code on the login screen (see Security). If you lose the authenticator and all recovery codes, an operator can clear it with make totp-disable.
• Tab timeout (session_idle_timeout_minutes, default 60, 0 = disabled): signs out a forgotten open tab after this long without activity. It is a browser-side timer only: closed tabs are unaffected, and every login expires on its own after 3 days without use, and after 30 days at most (AuthTokenTTL / AuthTokenMaxLifetime, see Security). Instance-local: not replicated by config sync.
• Active sessions: every live login for your identity with device, IP (trusted-proxy-aware), and last-seen; revoke one or sign out all others.
• Password policy & SSO: the breached-password check and the OIDC / GitHub single sign-on settings. The password policy and the SSO email allowlists are fleet-synced on managed members; the rest of the SSO config (enable flags, issuer, client credentials, public base URL) is per-member, so a fleet can offer an IdP on some members and not others.

Backend settings: alert_enabled, alert_apprise_api_url, alert_apprise_targets, alert_events, discovery_claim_alert_days. Outbound notification through an apprise-api container: which events fire, where they go, and how old an unaddressed discovery claim may get before it raises one. The destination URL and targets are instance-local; the event routing is fleet-synced. Full walkthrough on Alerting.

Backend settings: discovery_interval, discovery_on_startup, discovery_on_provider_create, model_prune_days

• UI Style: clean-saas (default), cyber-terminal, glassmorphism-lite - stored in localStorage uiStyle
• Theme: dark / light - stored in localStorage theme
• Accent Color: 10 preset swatches + custom hex picker - stored in localStorage accentColor
• Toast Notifications: 6-position visual picker (toastPosition) and 1s–15s auto-dismiss slider (toastTimeout)

Note: theme, ui_style, and accent_color are not in the backend AllowedSettings - they are localStorage-only and cannot be set via PUT /api/settings.

Backend settings: log_retention, stale_request_timeout. Everything else is localStorage-only.

• Session Persistence: Toggle for chat, arena, and conversation state across page reloads
• Arena History: Save match history toggle, limit (10/25/50/100), clear button
• Cache & Resets: Clear provider quota cache, reset dismissed error banners
• Sidebar Quotas: Show/hide the quotas pill (sidebarQuotaDisabled, inverted) and the refresh interval (quota_refresh_interval_min, a backend setting)
• Dashboard Refresh: Interval 10s/30s/1m/2m/5m/10m/Disabled (dashboardRefreshSec)
• Logging: Retention and stale-request timeout, plus purge actions for request logs and app logs

Read-only status panel with no backend settings to persist. Reflects which of the three log-export integrations are active (each enabled via its own environment variable) and shows enable instructions for those that are off:

• JSON logs (stdout): active when LOG_FORMAT=json
• Prometheus metrics: active when a dedicated METRICS_TOKEN is set. Without one, /metrics is reachable with normal admin authentication; with one, the bearer token replaces it
• OpenTelemetry logs (OTLP): active when OTEL_EXPORTER_OTLP_ENDPOINT is set, pushing the same structured logs to an OTel collector (logs only; standard OTEL_EXPORTER_OTLP_* vars apply, http/protobuf by default or OTEL_EXPORTER_OTLP_PROTOCOL=grpc)

Backend settings: backup_enabled, backup_interval, backup_son_retention, backup_father_retention, backup_grandfather_retention

• Backup: Download a PostgreSQL dump of the database (custom format, zstd-compressed at level 12 here and level 19 for scheduled backups, so restoring outside the app needs pg_restore 16 or later built with zstd; the postgres:16-alpine image qualifies). The list shows the combined size of every backup on disk.
• Restore: Upload a previously downloaded backup file to restore. The confirm dialog takes the backup's signature (optional; "Copy signature" on a signed backup's row puts it on the clipboard) so the dump is integrity-checked before it is applied; leaving it empty is allowed for backups that have no signature, but the dashboard then asks for an explicit "restore anyway" confirmation, because an unsigned dump's contents cannot be verified (see Security)
• Periodic Backup: Enable automatic scheduled backups with son/father/grandfather rotation (see backup settings above)

When periodic backup is enabled, backups are classified into three tiers:

• Son (daily): Keeps the most recent backup from each of the last backup_son_retention days
• Father (weekly): Keeps the most recent backup from each of the last backup_father_retention weeks (excluding those already kept as sons)
• Grandfather (monthly): Keeps the most recent backup from each of the last backup_grandfather_retention months (excluding sons and fathers)
• All other backups are pruned automatically

When enabling periodic backup for the first time, a confirmation dialog shows which existing backups would be removed under the rotation scheme.

A background scheduler (started about a minute after the server boots) drives periodic backups - there is no external cron job. While backup_enabled is true, each due cycle it creates one backup with pg_dump, then immediately applies the son/father/grandfather rotation above (pruning any backup outside the retention tiers), and sleeps for backup_interval (default 24h, floored at 5 minutes, capped at 168 hours) before repeating. The interval is measured from the newest scheduled backup on disk, not from process start, so a restart or redeploy inside the interval sleeps out the remainder rather than taking an extra backup. A dump is written under a temporary name and renamed once complete, so a process killed mid-dump leaves nothing that could count as a backup. backup_enabled, backup_interval, and the retention counts are re-read every cycle, so changes take effect without a restart. Each scheduled backup publishes a backup.created event, which surfaces as a success toast in the dashboard (when a session is connected) and as an App Logs entry. The manual Download / Restore buttons are separate, on-demand actions.

Backend settings: rate_limit_enabled, rate_limit_ip_enabled, rate_limit_rps, rate_limit_burst, rate_limit_ip_rps, rate_limit_ip_burst, rate_limit_max_wait_ms. rate_limit_tpm is writable through the API but has no control in this section.

The largest section, laid out as four groups in a two-column grid: Failover, Hedging, Rate Limit (429) Handling, and Adaptive Concurrency.

Failover group: circuit_breaker_enabled, failover_on_rate_limit, circuit_breaker_threshold, circuit_breaker_span_models, circuit_breaker_cooldown, circuit_breaker_quota_pin_max, circuit_breaker_backoff_max.

• Failure Threshold: Consecutive failures before a model's circuit opens (default 5).
• Models Before Provider Skip: How many of a provider's models must have an open circuit before the provider itself is skipped for every model (default 2, range 1-100). At 1 the first open circuit sidelines the whole provider.
• Cooldown Period: How long an open circuit stays open before it goes half-open (default 60s).
• Backoff Limit: Double the cooldown for every half-open probe that fails, up to this limit (default 15 minutes). Zero switches backoff off, and releases a backoff already in force within about 30 seconds. See Probe backoff.
• Quota Pin Limit: When a circuit opens on a spent quota window, hold it open until the provider's quota actually resets rather than re-probing every cooldown, up to this ceiling (default 24h). Zero switches pinning off, and releases a pin already in force within about 30 seconds.
• The number of half-open probe successes needed to close the circuit is fixed in code (HalfOpenMaxProbes, default 1) and is not a runtime setting.

Hedging group: hedging_enabled, hedge_delay. Off by default. When on, a streaming request that has waited hedge_delay for its first token also fires a backup provider and keeps whichever answers first. The notice under the toggle spells out the trade-off: on slow starts this doubles the upstream request, so provider rate limits and capacity are consumed faster and a backup that ignores cancellation can keep generating in the background. Full mechanics under Request hedging.

Rate Limit (429) Handling group: rate_limit_classify_enabled, rate_limit_saturation_max_wait, rate_limit_recent_success_window, circuit_breaker_open_on_exhaustion, failover_exhaustion_status_429, and, last in the group, server_error_retry_enabled. The 429 settings read each 429 to tell a provider that is briefly at capacity from one whose quota window or balance is spent, and decide what the client sees when every member of a group is unavailable. See 429s: saturated vs exhausted.

• Retry a Transient 5xx Once: Let the last candidate back off briefly and try once more on a 500, 502, 503 or 504 before the error reaches the client.

Adaptive Concurrency group: inflight_limiter_enabled, inflight_grow_after, inflight_forget_after. Learns each provider's real concurrency from its busy 429s, shrinking the allowance when one arrives and growing it back on clean completions. See Adaptive in-flight limiter.

Backend settings: request_timeout, key_cache_ttl, ttft_timeout, stream_stall_timeout, upstream_header_timeout

• Request Timeout: Base per-request timeout (default 1m0s). Streaming requests get 10x this.
• Key Cache TTL: How long a decrypted provider key stays in memory (default 10m0s).
• TTFT Timeout: Time-to-first-token probe timeout for streaming requests (default 1m0s). Set to 0s to disable.
• Stream Stall Timeout: Maximum silence during streaming before termination (default 30s). After 50 chunks the effective timeout is multiplied by 3.
• Upstream Header Timeout: Maximum wait for a provider to send its response headers (default 2m0s). Caps a non-streaming request whose Request Timeout is longer, and a streaming provider that thinks before its headers arrive. Set to 0s for no limit.

The Settings page header and its collapsible sections. Each section's controls are shown expanded in the screenshots that follow.

Settings page - Model Discovery section: the automatic toggles (discover on startup, discover on provider creation, re-discovery interval) alongside the manual "Discover All Models" trigger and a live count of discovered models, providers, and last run.

Settings page - Appearance section expanded, showing the UI Style cards (Clean SaaS, Cyber Terminal, Glassmorphism), Theme toggle, and Accent Color picker.

The three UI styles applied to the dashboard (dark mode, each style's default accent):

Left to right: Clean SaaS (default), Cyber Terminal, Glassmorphism.

Settings page - Data Storage and Logging section: log retention and stale-request timeout with one-click purge of request and app logs, cache and dismissed-banner resets, sidebar quota-badge controls, browser-local session persistence (chat, arena, conversation), arena history limits, and the dashboard refresh interval.

Settings page - Observability & Log Export section: read-only status of the three log-export integrations. JSON logs enabled here; Prometheus and OTLP disabled, each showing its copyable enable instruction.

Settings page - Rate Limiting section expanded, showing the enable toggle, RPS selector, and Burst selector.

Settings page - Proxy section, showing the request timeout, key cache TTL, TTFT Timeout, and Stream Stall Timeout settings.

Settings page - Circuit Breaker & Failover section: the failover column with cooldown, failure threshold and the quota-pin controls, and the Hedging column with its trade-off notice beneath the toggle.

Settings page - Database Backup section, showing backup and restore controls.

The docker-compose.yml sets up the following services. For local development, run it with the compose.dev.yml overlay, which mounts the Docker socket and turns on DEBUG_LOG and ALLOW_EMBED: see Development.

Environment variables (docker-compose.yml):

environment:
  - MASTER_KEY=${MASTER_KEY:?MASTER_KEY must be set in .env}
  - POSTGRES_USER=${POSTGRES_USER:-modelhotel}
  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
  - POSTGRES_HOST=db
  - POSTGRES_DB=${POSTGRES_DB:-modelhotel}
  - ADMIN_TOKEN=${ADMIN_TOKEN:-}
  - ALLOW_HTTP_PROVIDERS=false
  - ALLOW_EMBED=false
  - DATA_DIR=/data
  - RATE_LIMIT_ENABLED=true
  - DEBUG_LOG=false
  - CORS_ORIGINS=http://localhost:5173,http://localhost:${HOST_PORT:-8081}
  - WEBAUTHN_RP_ID=${WEBAUTHN_RP_ID:-}
  - WEBAUTHN_RP_ORIGINS=${WEBAUTHN_RP_ORIGINS:-}
  - ALLOWED_PROVIDER_HOSTS=
  - TRUSTED_PROXIES=
  - KNOWN_PROXIES=

There is no env_file:, so this list is everything the app receives: a variable set only in .env and not referenced here has no effect. Add a line for it (or edit the hardcoded value).

Graceful shutdown. On SIGTERM (docker compose stop, docker compose down, a container restart) the server winds down in stages rather than dropping what is in flight. It cancels the background maintenance loops, ends every open SSE stream and proxied stream so they finish with a proper terminal frame, then stops accepting and drains the HTTP requests still running, joins the background loops, flushes the pending audit rows, flushes the application log writer, flushes the OTLP log exporter if one is configured, and closes the database pool last.

Each stage is budgeted. Worst case, in order: 10s HTTP drain + 35s background join + 10s audit drain (one record's 5s insert plus the 5s retention prune it piggybacks) + 5s app-log writer stop

• 5s OTLP flush = 65s. The join budget is the 30s ceiling of the scheduled-disable sweep plus a 5s margin: that sweep deliberately finishes the statement it has already started, and the join waits it out rather than letting the database pool close underneath it. The retention and stale-log sweeps are the other way round. They carry no ceiling at all, so that a first sweep over a large backlog runs as long as the database needs, and when the join budget expires they are cancelled rather than awaited. The closes around all of this (the event bus, the proxy handler, discovery, the docker client, the rate limiters and the database pool) carry no budget of their own, so the stop_grace_period: 75s on the app service is a ceiling with headroom over the 65s, not the sum. Docker's default grace is 10s, which would SIGKILL the process partway through the drain and lose the audit rows and the last log lines, so the setting is not optional. If you run Model Hotel outside this compose file (Kubernetes, systemd, your own compose), give it the same 75s.

A third service sits commented out at the bottom of docker-compose.yml. Uncomment it to run a stateless caronc/apprise container, then switch alerting on in Settings and press "Set up alerts": the wizard checks http://apprise:8000, builds the destination URL for you (ntfy, Telegram, Discord, email, or a raw Apprise URL), tests it, and saves at Finish. It is not exposed to the host, only Model Hotel reaches it, and only event summaries are sent: no request content. See Alerting.

git clone https://github.com/hugalafutro/model-hotel.git
cd model-hotel

cp .env.example .env
nano .env          # set a strong MASTER_KEY and POSTGRES_PASSWORD

docker compose up --build

On first launch the auto-generated admin token is printed once, in a framed box labelled ADMIN TOKEN (save now ...). To find it again in the logs:

docker compose logs app | grep -A 3 "ADMIN TOKEN"

It is shown once and stored only as a SHA-256 hash, so it cannot be read back later. If you lose it, delete .data/admin-token and restart to generate a new one. To pick the token yourself instead, set ADMIN_TOKEN in .env before the first start; the box is printed on that first boot either way, showing the token you chose.

The Dockerfile is a three-stage build.

• Base: node:26-alpine, with pnpm 12.11.2 installed via npm install -g [email protected] (the version packageManager names; pnpm self-switching is off, see pmOnFail in web/pnpm-workspace.yaml).
• Working directory: /app/web.
• Copies package.json, pnpm-lock.yaml and pnpm-workspace.yaml before the sources, then installs with --frozen-lockfile. The workspace file must be present: pnpm 12 reads the dependency overrides from it, and without it the lockfile check fails.
• Also copies web-shared/, the shared frontend modules the app pulls in through the @web-shared/* alias.
• Build command: pnpm run build:docker, which skips tsc -b. Type-checking is gated by the pre-push hook and by CI's full pnpm run build, so the image build stays off the typecheck path.

• Base: golang:1.27.2-alpine, working directory /app.
• Copies the frontend dist/ from stage 1 into cmd/server/static/, the directory the Go binary embeds.
• Build command: go build -o server ./cmd/server/, with -ldflags stamping the VERSION and COMMIT build args into the binary. COMMIT is passed in because .git is excluded from the build context.

• Base: alpine:3.24, named runtime so a cached build can exclude just this stage (buildx --no-cache-filter=runtime) and still pick up base-image security patches.
• Runs apk upgrade then installs ca-certificates, postgresql16-client and su-exec.
• Creates a non-root user appuser with uid 1000, which matches the typical host user.
• Copies the server binary to /app/server and docker-entrypoint.sh to /usr/local/bin/, and chowns /app to appuser.
• Exposed port: 8080. Healthcheck: wget --spider http://localhost:8080/health, every 30s with a 10s timeout, a 40s start period and 3 retries.
• ENTRYPOINT: docker-entrypoint.sh. CMD: ["./server"].

The entrypoint starts as root only long enough to fix ownership, then drops privileges:

1. Creates /data/backups and gives appuser ownership of /data, /data/backups and an existing /data/admin-token. It deliberately does not recurse into /data/pgdata: those files belong to the PostgreSQL container and rechowning them would break it.
2. If /var/run/docker.sock is mounted, reads the socket's group id and makes that the process's primary group, so the non-root user can talk to the daemon. A root-owned socket (gid 0) is skipped, since no group membership can grant access there.
3. exec su-exec appuser ... to run the server unprivileged.

Because the process runs as uid 1000, the ./.data bind mount on the host ends up owned by uid 1000. If your host user has a different uid you may need to adjust ownership before Model Hotel can write to it.

The template lives in the repository: .env.example. Copy it to .env and edit that copy. It is a starting point, not the full list: the app reads every variable in the tables above from its process environment whether or not the template mentions it. Under Docker Compose, though, a .env entry reaches the app only if the app service's environment: block in docker-compose.yml references it (see What you actually need to touch for the stock list); add a line there for anything else you set.

What you must set before the first start:

1. MASTER_KEY (openssl rand -base64 32): encrypts provider API keys at rest. Rotating it invalidates every stored key.
2. POSTGRES_PASSWORD (openssl rand -hex 16): the database password, unless you set DATABASE_URL instead.
3. Nothing else is required. ADMIN_TOKEN is optional: leave it empty and one is generated and printed on first launch.

Key Architecture Points:

1. Environment variables are loaded once at startup via godotenv.Load() and the config.Load() function.
2. Database settings use a 30-second cache with change notifications via Subscribe() for immediate updates.
3. Rate limiting has a hard kill-switch (RATE_LIMIT_ENABLED env var) that completely disables the middleware when false.
4. Provider host validation always allows built-in providers; ALLOWED_PROVIDER_HOSTS is for custom/local providers and, once non-empty, is a strict allowlist for every other host.
5. Admin token is auto-generated on first run and stored as a SHA-256 hash.