Self-hosted in 5 minutes

Prerequisites

• Linux server (Ubuntu 22.04+ or RHEL 9+ recommended)
• Docker Engine 24+ with the Compose plugin v2.24.4 or newer (docker compose version prints it; the port lockdown in step 06 uses !override, which older plugins reject)
• At least 4 GB RAM — 8 GB+ recommended under concurrent load
• At least 30 GB disk — the backend image is about 1 GB (fastembed ONNX embedding model baked in); budget additional space for the PostgreSQL data volume, build cache, and OS
• A domain name with DNS pointing to the server (for HTTPS)
• At least one LLM API key (Groq and Google Gemini have free tiers)

Evaluating on a laptop instead? Docker Desktop (macOS, Windows, Linux) includes Compose v2 and works the same way — skip the HTTPS and port steps and open the UI on localhost.

The same requirements apply for a production rollout — but you don't have to deploy it yourself. We set Savvina up with you and issue an evaluation licence so you can run it on real data first; see the production checklist below for the production-specific settings, or talk to us to get started.

01Prepare the environment

Clone the repository (it holds the Compose file and .env.example; the application itself comes from Docker Hub in step 03), copy the example env file, and record your host user so mounted volumes stay writable:

git clone https://github.com/savvina-ai/savvina
cd savvina
cp .env.example .env
chmod 600 .env

# Linux / WSL: run the containers as your user
printf '\nLOCAL_UID=%s\nLOCAL_GID=%s\n' "$(id -u)" "$(id -g)" >> .env

Open .env and set the one value it needs — a password for the bundled app database:

python -c "import secrets; print(secrets.token_urlsafe(24))"

02Choose a database mode

COMPOSE_PROFILES=local-db
APP_DB_PASSWORD=<strong-password>
# DATABASE_URL is derived: postgresql+asyncpg://savvina:<strong-password>@db:5432/savvina_app

# COMPOSE_PROFILES=local-db
APP_DB_PASSWORD=unused   # must be non-empty; ignored once DATABASE_URL is set
DATABASE_URL=postgresql+asyncpg://USER:[email protected]:5432/savvina_app
# Append ?ssl=require if your provider enforces SSL (most do)

03Pull and start

On an internet-facing server, create the port override from step 06 before the first start — until then, whoever opens the UI first becomes the admin.

Pull the pre-built images and start the stack. Nothing compiles, and the embedding model is already inside the backend image:

docker compose pull
docker compose up -d --no-build

latest is the newest release. To pin one, add SAVVINA_IMAGE_TAG=v2.1.1 (any tag from v2.1.0 on, listed on the releases page; earlier releases have no images) to .env before pulling — this pins the code, dependencies and migrations together.

Building from source instead (you changed the code, or your host cannot reach Docker Hub) is one command, but the first build takes a while:

docker compose up --build -d

This starts the core services: backend (FastAPI on port 8000), frontend (React/Nginx, published on APP_PORT, default 3000), and db (PostgreSQL, local-db profile only). Migrations run on every start, so the first boot can take a minute or two.

Verify all services are healthy:

docker compose ps

Confirm the backend started correctly — look for alembic's Context impl PostgresqlImpl line, then Embedding model loaded and Uvicorn running (these need LOG_LEVEL=INFO, the default):

docker compose logs backend --tail 30

04Create the admin account

Open http://localhost:3000 on the server — from your workstation, tunnel it with ssh -L 3000:127.0.0.1:3000 you@server — or your proxy's address once step 05 is done. The first person to open the UI is taken to theInitial setup screen. Enter an email, an optional name and a password (at least 12 characters, with an uppercase letter, a digit and a special character). This screen appears only once — the registration endpoint closes permanently as soon as any account exists.

A two-step setup wizard then walks you through connecting a database and adding an LLM provider — paste your API key there, or later under Settings → LLM Providers.

Reaching the UI at any address other than http://localhost:3000 — a LAN IP, a different port, your domain — requires that exact origin in CORS_ORIGINS, or login fails with 403 Origin not allowed. Step 05 sets it for your domain.

05Configure HTTPS

The stack serves plain HTTP and does not terminate TLS. For anything reachable beyond the server itself, put a TLS-terminating reverse proxy in front of the frontend and expose only the proxy.Caddy needs the least configuration — it obtains and renews Let's Encrypt certificates on its own:

Install Caddy:

apt install caddy -y

/etc/caddy/Caddyfile:

yourdomain.com {
    header Strict-Transport-Security "max-age=31536000; includeSubDomains"
    reverse_proxy 127.0.0.1:3000
}

Reload Caddy to pick up the new config:

systemctl reload caddy

Then tell the stack it is behind TLS. Add your domain to CORS_ORIGINS, set BEHIND_TLS_PROXY (this is what marks the session cookie Secure and turns on HSTS on API responses — the backend deliberately does not infer it from X-Forwarded-Proto), and name the range the proxy connects from so nginx takes the real client IP from X-Forwarded-For instead of rate-limiting every user as one:

CORS_ORIGINS=["https://yourdomain.com"]
BEHIND_TLS_PROXY=true
TRUSTED_LB_CIDR=172.16.0.0/12   # the Compose network's subnet — confirm it below

Docker hands each Compose project a subnet from its default address pools, so 172.16.0.0/12 covers the usual case but not a host that already runs several projects, where the pools spill into 192.168.0.0/16. Print the subnet the stack actually got (the network is named after the checkout directory plus savvina) and use that if it differs:

docker network inspect savvina_savvina -f '{{(index .IPAM.Config 0).Subnet}}'

Recreate the two containers so they pick up the new environment — a plain restart reuses the old one:

docker compose up -d backend frontend

Any other proxy (nginx, Traefik, HAProxy, a cloud load balancer) works the same way. Four requirements: send the Strict-Transport-Security header from the proxy (the backend only sends it on /api/*), disable response buffering and allow read timeouts of at least 300 s so chat streaming does not stall (900 s for semantic model generation), pass the client address in X-Forwarded-For, and set TRUSTED_LB_CIDR to the range the proxy really connects from — a cloud load balancer needs its own range.

06Lock down exposed ports

By default, docker-compose.yaml publishes every port on all interfaces — 3000 (frontend; container port 8080), 8000 (backend API) and 5434 (app database), plus 5435/3307 (sample databases) and 11434 (Ollama) when those profiles are on. Rebind them to localhost with an extra Compose file, and keep the shipped docker-compose.override.yaml (!override needs Compose v2.24.4+):

# docker-compose.prod.yaml  (new file — keep the shipped docker-compose.override.yaml)
services:
  backend:
    ports: !override
      - "127.0.0.1:8000:8000"
  frontend:
    ports: !override
      - "127.0.0.1:${APP_PORT:-3000}:8080"
  db:
    ports: !override
      - "127.0.0.1:5434:5432"
  sample-postgres:
    ports: !override
      - "127.0.0.1:5435:5432"
  sample-mysql:
    ports: !override
      - "127.0.0.1:3307:3306"
  ollama:
    ports: !override
      - "127.0.0.1:11434:11434"

Then add it to .env:

COMPOSE_FILE=docker-compose.yaml:docker-compose.override.yaml:docker-compose.prod.yaml

07Backups

All application state — user accounts, saved connections (with encrypted credentials), chat history, query cache — lives in volumes/app-db/ (local-db profile). Back it up regularly with pg_dump:

docker compose exec db pg_dump -U savvina savvina_app > backup.sql

If using an external/managed PostgreSQL, backups are your provider's responsibility — enable automated snapshots and PITR in your provider's console.

Also back up the generated secrets separately — a database dump is useless without the ENCRYPTION_KEY that decrypts the credentials in it:

docker compose exec backend cat /app/data/secrets.env

08Sample databases (optional)

The test-dbs profile starts two pre-seeded databases so you can evaluate Savvina AI without connecting to a real data source:

Add the profile in .env rather than on the command line — a --profile flag replaces the value from .env and would silently stop the app database from starting:

COMPOSE_PROFILES=local-db,test-dbs

# then
docker compose up -d

The sample containers publish ports 5435 and 3307 on all interfaces, and when SAMPLE_POSTGRES_PASSWORD and SAMPLE_MYSQL_PASSWORD are left empty they fall back to the published password savvina_demo (SAMPLE_MYSQL_ROOT_PASSWORD to savvina_demo_root) — on a reachable server set all three, or bind the ports to 127.0.0.1 as in step 06. Add them from Connections with user savvina. Demo data only — never a primary data source.

09Local LLM with Ollama (optional)

Run a local Ollama instance if you want fully offline inference. A GPU is required for acceptable performance. Add the profile and the base URL in .env — setting OLLAMA_BASE_URL is what makes Ollama appear as a provider in the UI:

COMPOSE_PROFILES=local-db,local-llm
OLLAMA_BASE_URL=http://ollama:11434

# then
docker compose up -d
docker compose exec ollama ollama pull llama3

Configure it via Settings → LLM Providers → + Add Ollama (Local) config and select the pulled model.

10Updating

Update the checkout, pull the new images and recreate the containers. Database schema migrations apply automatically on startup via alembic upgrade head — no manual migration step required. The volumes/ directory is never touched during updates.

git pull                     # compose file and .env.example for the new release
# Pinned? bump SAVVINA_IMAGE_TAG in .env first
docker compose pull
docker compose up -d --no-build

Building from source: git pull, then docker compose up --build -d. Each release is listed on the changelog.

Production checklist

Health check

The backend exposes a health endpoint used by Docker Compose and your load balancer:

curl http://localhost:8000/health
# {"status": "ok", "app": "Savvina AI"}

Corporate TLS proxies

If your network uses a TLS-intercepting proxy (Zscaler, Netskope, Palo Alto), LLM API calls may fail with certificate errors. Set in .env:

VERIFY_SSL=false

This affects only LLM provider HTTP clients — not the asyncpg database TLS stack.

Troubleshooting

docker compose logs backend

docker compose up -d backend

docker compose ps db
docker compose logs db --tail 20

docker compose logs backend --tail 30