Configuration¶

Every environment variable LogsTotal reads from .env, how to generate its secrets, and how the Docker Compose profiles work.

All application configuration lives in .env in the install directory. .env.example is the copy-paste template with safe defaults; this page is the annotated reference. The fleet deploy tooling reads its own DEPLOY_* variables from deploy.env instead — see DEPLOY_* reference. After editing .env, follow Apply configuration changes.

Generating secrets and keys¶

Generate everything at once, on the deployment host, from the install directory:

./logstotal gen-secrets             # print a copy-paste block of all secrets
./logstotal gen-secrets -- --write  # fill them into .env (only empty/placeholder keys; never clobbers real values)

This covers SECRET_KEY, ADMIN_PASSWORD (printed once when newly generated), POSTGRES_PASSWORD, REDIS_PASSWORD, the Garage-style S3_ACCESS_KEY/S3_SECRET_KEY, and GARAGE_RPC_SECRET/GARAGE_ADMIN_TOKEN. --write only touches keys that are still unset or a placeholder, so it is safe to re-run. To choose your own admin password, set ADMIN_PASSWORD in .env before running it.

To generate a single value instead, run one of these anywhere python3 or Docker is available:

Paste the basic-auth hash into BASIC_AUTH_HASH with single quotes, so Docker Compose does not treat $ as variable expansion.

Concurrency: HUEY_WORKERS, TOOL_MAX_WORKERS and the per-tool threads multiply into CPU pressure — see Scaling for the model and ./logstotal recommend-scaling.

Docker Compose profiles¶

COMPOSE_PROFILES in .env selects which bundled services Docker Compose starts alongside web, worker and Redis. Combine them with commas:

Examples:

COMPOSE_PROFILES=postgres                  # single host, PostgreSQL instead of SQLite
COMPOSE_PROFILES=proxy                     # single host, HTTPS via Caddy
COMPOSE_PROFILES=postgres,s3,workers       # fleet control plane (bundled services)
COMPOSE_PROFILES=postgres,s3,proxy,workers # fleet control plane behind HTTPS

COMPOSE_PROFILES decides whether the bundled PostgreSQL is used. The image entrypoint switches from SQLite to PostgreSQL only when POSTGRES_PASSWORD is set and postgres is in COMPOSE_PROFILES (or an external POSTGRES_HOST is configured), then builds the database URLs itself — no manual URL editing. The rule cuts both ways:

• A POSTGRES_PASSWORD without the postgres profile keeps the app on SQLite and logs a warning, rather than waiting for a postgres host Compose never started.
• COMPOSE_PROFILES=postgres without a password also stays on SQLite.

An explicit DATABASE_URL always wins. ./logstotal backup resolves the database the same way, so a leftover password never makes it dump the wrong engine. Avoid # @ % ? in the password, or URL-encode them.

Cookies over plain HTTP¶

With DEBUG=false, auth cookies are marked Secure, and browsers silently drop them on http:// — login appears to succeed but never sticks. Set COOKIE_INSECURE=true for any deployment served over plain HTTP (Docker without a proxy, local development on :8000). Once TLS is in front — the proxy profile or your own reverse proxy — set COOKIE_INSECURE=false (or remove it); HTTPS with Caddy says which ENABLE_HSTS value goes with each TLS mode. ./logstotal quickstart sets COOKIE_INSECURE=true for a plain-HTTP start, and ./logstotal proxy:enable sets it to match the TLS mode it configures.

The browser's clipboard API also requires HTTPS, so every "Copy" button falls back to an older mechanism on plain HTTP. It works, and says so when a strict browser refuses it.

AI provider base URLs¶

AI providers are configured on /admin/ai, not in .env — the base URL, model, API token, timeout and system prompt all live there. Two things about the base URL look like bugs the first time you meet them.

A private or internal address is allowed by default. The intended setup for this feature is a model running on the same machine, so http://localhost:11434/v1 (Ollama) or http://127.0.0.1:1234/v1 (LM Studio) is expected. AI_REQUIRE_PUBLIC_HOST=true restricts base URLs to publicly-routable addresses, which is the right setting when your admin accounts are not fully trusted — and it breaks every local model, so it is not the default. Cloud metadata addresses are refused either way. See AI job analysis for the full boundary.

In Docker, localhost is the container, not your machine. The completion request is made by the worker, so the base URL is resolved inside the worker container. If Ollama runs on the Docker host, http://localhost:11434/v1 reaches the worker container itself, and the run fails with "could not reach the provider". Use the host gateway instead:

http://host.docker.internal:11434/v1

That name resolves on Docker Desktop (macOS, Windows) and OrbStack. On Linux, host.docker.internal needs an explicit mapping — add extra_hosts: ["host.docker.internal:host-gateway"] to the worker service, or point the base URL at the host's LAN or WireGuard address. Also make sure the model listens on more than loopback: Ollama binds 127.0.0.1 by default and needs OLLAMA_HOST=0.0.0.0 before anything outside the host can reach it.

The Test button on /admin/ai is the fastest way to tell these failures apart: it runs a real one-word completion and reports the error immediately. Test runs in the web process; real runs happen in the worker. On a single host both reach the same network, so a passing test means the feature works. In a fleet, a passing test only proves the control plane can reach the model — the base URL must also resolve and connect from every worker host.

Environment variable reference¶

Every setting, grouped by concern. A default applies when the key is absent from .env.

Required¶

Redis and Huey¶

PostgreSQL¶

Used with COMPOSE_PROFILES=postgres or an external PostgreSQL server.

S3 storage¶

Used with STORAGE_BACKEND=s3.

Reverse proxy and TLS¶

Used with COMPOSE_PROFILES=proxy. The four PROXY_TLS modes, what each needs, and the COOKIE_INSECURE / ENABLE_HSTS pair each one requires are in HTTPS with Caddy. ./logstotal proxy:enable -- --tls <mode> — or DOMAIN=... QUICKSTART_TLS=<mode> ./logstotal quickstart on a first deploy — sets all of them together. They have to agree: when they do not, login fails silently.

Docker Compose¶

Application¶

Workers¶

Config paths¶

DEPLOY_* reference¶

The fleet deploy tooling (./logstotal deploy, upgrade and the deploy:* commands) does not read .env. It reads DEPLOY_* and FLEET_* variables from deploy.env or from the environment of the command. Every one of them, with its default and where it is meant to be set, is in the Fleet reference; FLEET_FROM and the other FLEET_* variables are in Taking the record somewhere else.

Related: Security · Scaling · Prerequisites · Fleet reference · Docs index