Deployment Tiers

FreeSDN uses a single docker-compose.yml base file for every environment. You choose a scale tier with an env file (--env-file .env.<tier>) and opt into optional capabilities via COMPOSE_PROFILES. There is no separate production compose file - the same base runs everything.

Two independent axes

Axis	What it controls	How you set it
Tier (Lite / Pro / Max / Dev)	Worker count, concurrency, resource limits	--env-file .env.<tier>
Features (cameras, pooling, DR, …)	Optional capabilities at any tier	COMPOSE_PROFILES= in the env file

A homelab and an enterprise deployment run the same code and the same image. The differences are worker count and memory limits. Cameras, connection pooling, and off-site DR are features you enable at any tier - a Lite homelab can run cameras; a Max enterprise deployment can skip them.

Tier summary

	Lite	Pro	Max	Dev
Intended use	Homelab / personal	SMB, dozens-hundreds of devices	Enterprise / multi-site	Local development
API workers (WEB_CONCURRENCY)	1	2	4	1 (uvicorn --reload)
Celery worker queues	All queues on one worker	default,priority (quick lane)	default,priority	All queues
I/O worker (io-worker profile)	No	Yes	Yes	No
Flower (monitoring profile)	No	Yes	Yes	No
PgBouncer (pooling profile)	No	Optional	Yes	No
Off-site DR (dr profile)	No	Optional	Yes	No
HA overlay (docker-compose.ha.yml)	No	No	Yes (opt-in)	No
Resource limits	Small	Moderate	Large	Minimal

Tip

Every tier runs the same core always-on services: PostgreSQL 18.4, TimescaleDB (logdb), Valkey 8.1 (service name redis retained for drop-in compatibility), api, worker, scheduler (Celery beat), pg-backup, and the Caddy edge. Only the edge publishes host ports; all data-tier ports are internal.

Up commands

# Lite  -  homelab
docker compose --env-file .env.lite up -d

# Pro  -  SMB
docker compose --env-file .env.pro up -d

# Max  -  enterprise
docker compose --env-file .env.max up -d

# Max + HA overlay (Valkey Sentinel + Postgres standby)
docker compose --env-file .env.max -f docker-compose.yml -f docker-compose.ha.yml up -d

# Dev  -  local development with hot-reload
docker compose -f docker-compose.yml -f docker-compose.dev.yml --env-file .env.dev up -d

The one-command installer handles tier selection automatically:

./install.sh                                   # auto-detect
./install.sh --tier pro --domain sdn.example.com

Core always-on services

Container	Role
postgres	Primary relational DB - 18 schemas, PostgreSQL 18.4
logdb	TimescaleDB - metrics, syslog, NetFlow, health snapshots
redis	Valkey 8.1 - cache, session store, Celery broker (DB 0/1/2)
api	FastAPI + Gunicorn + Uvicorn workers
worker	Celery worker - quick/priority lane (Lite: all queues)
scheduler	Celery beat - scheduled tasks
pg-backup	Daily GPG-encrypted dumps of both DBs
edge (or edge-nginx)	Edge proxy - TLS termination, SPA serving, API reverse proxy

Tier resource sizing

Defaults from the env example files:

Resource	Lite	Pro	Max
POSTGRES_MEM_LIMIT	1 G	2 G	4 G
LOGDB_MEM_LIMIT	1 G	2 G	4 G
REDIS_MEM_LIMIT	256M	768 M	1 G
API_MEM_LIMIT	768 M	1 G	2 G
WORKER_MEM_LIMIT	768 M	1 G	2 G
WEB_CONCURRENCY	1	2	4
CELERY_CONCURRENCY	2	4	8

Pro tier: split worker queues

The default .env.pro sets COMPOSE_PROFILES=io-worker,monitoring, which splits Celery into two workers:

• worker - handles default and priority queues (heartbeats, alert evaluation, notifications, backup orchestration)
• worker-io - handles discovery, sync, and metrics queues (vendor Adapter calls, device scans)

This prevents a slow vendor API call from starving quick tasks such as alert notifications.

Migrating from docker-compose.prod.yml

If your existing deploy uses -f docker-compose.prod.yml, it still works - that file is now a thin include: shim of the base. To adopt the tier model, copy the matching example env file and switch to --env-file .env.pro (or your tier). The base file defaults to production settings: ENVIRONMENT=production, Gunicorn, read-only rootfs, non-root users, internal-only data tier.

Next steps: Configuration - fill in your env file. Compose Profiles - full list of optional feature profiles.