Self-Hosting Configuration

This page is the complete configuration reference for a self-hosted Owlat instance. For step-by-step setup, see Self-Hosting.

Two Configuration Layers

Docker Environment Variables

These go in the .env file at the project root. Docker Compose reads them when starting containers.

Convex Backend

Public URLs

These must be reachable from the user's browser — do not use Docker-internal hostnames.

MTA Configuration

Port Overrides

All ports can be changed if the defaults conflict with existing services.

The Convex, MTA HTTP, and dashboard ports default to localhost-only binding (127.0.0.1). CONVEX_BIND (default 127.0.0.1) controls the interface the Convex backend binds to, and REDIS_PASSWORD sets the Redis auth password.

Redis and ClamAV publish no host port — they are reached only over the internal Docker network (redis:6379, clamav:3310), so there is no REDIS_PORT/CLAMAV_PORT host-override knob. (CLAMAV_PORT is set on the MTA container as the internal address its scan client dials; it does not map a host port.)

Analytics (Optional)

Deployment Mode

These control which UI the web app shows and whether in-app updates can run. The defaults match a self-hosted install — you rarely need to change them.

Image Pinning (Optional)

The compose file pins upstream images to minor versions via dedicated *_VERSION vars, each with a hard-coded default. Override only to pin a different version; production release compose files further lock these to @sha256 digests.

Owlat's own images (web, mta, updater, convex-deploy, code-worker) are tagged with OWLAT_VERSION — the image pull tag defaults to latest, while the in-container build arg defaults to the dev local-build sentinel. The release pipeline writes the pinned tag, so do not edit OWLAT_VERSION, OWLAT_GIT_SHA, or OWLAT_BUILD_DATE by hand.

Convex Environment Variables

These are set after deploying functions. They control application-level behavior inside the Convex backend.

npx convex env set VAR_NAME "value" \
  --url http://localhost:3210 \
  --admin-key <your-admin-key>

Set These for Normal Operation

Set all of these on any real deployment. In code, most are read with sensible fallbacks and won't crash a function if missing — but auth redirects, unsubscribe links, and CORS will be wrong without them.

Sender Identity

LLM Provider (Optional)

Owlat talks to a single pluggable LLM provider (ADR-007). The same config powers AI agent replies, translations, knowledge-graph embeddings, and the visualization agent. Anything that speaks the OpenAI Chat Completions / Embeddings shape works (OpenAI, OpenRouter, Ollama, local vLLM/LM Studio). Only set these if you turn on an AI feature flag.

Other Integrations (Optional)

For the complete variable reference including AWS SES, Resend, and inbound-channel webhooks, see Environment Variables.

Service Topology

The updater sidecar has no public port — the web app reaches it at http://updater:3200 over the Docker network. It mounts only OWLAT_INSTALL_DIR read-write so it can write a new compose template, and reaches the Docker API through the least-privilege docker-socket-proxy sidecar (which mounts the socket read-only) via DOCKER_HOST=tcp://docker-socket-proxy:2375 — it no longer mounts the Docker socket directly.

The optional caddy service (--profile tls) is a reverse proxy that terminates TLS via Let's Encrypt and fronts web, convex, and mta on subdomains. Edit Caddyfile to match your domains before bringing it up, or front the stack with your own reverse proxy instead.

The code-worker sidecar (--profile inbox-codetasks, also available via --profile dev) is the AI coding agent that picks up code tasks. It reads the LLM_* and GITHUB_* variables and is off by default.

Volumes