Host Requirements

FreeSDN runs as a Docker Compose stack. The host requirements depend on which deployment tier you choose, but the baseline prerequisites are the same for every tier.

Software prerequisites

Requirement	Minimum version	Notes
Docker Engine	24+	CE or EE; rootless mode supported but not tested
Docker Compose	v2 (the docker compose plugin, not docker-compose v1)	docker compose version must print v2.x
Operating system	Any 64-bit Linux distribution with a 5.x+ kernel	Ubuntu 22.04 LTS, Debian 12, RHEL 9, Rocky Linux 9 are the reference platforms
Python (optional)	3.11+	Only needed if you run scripts/selfheal.py or scripts/ha_drill.py on the host

Note

FreeSDN is developed and tested on Linux. macOS (Docker Desktop) and Windows (WSL 2) work for development with the dev tier; they are not recommended for production because of Docker Desktop’s performance profile and VM networking overhead.

CPU and RAM by tier

The numbers below are practical minimums - the stack can start below them, but will degrade under real load. For production, add headroom.

Tier	Use case	Minimum CPU	Minimum RAM	Recommended RAM
Lite	Homelab, a handful of devices, personal use	2 cores	4 GB	6 GB
Pro	SMB, dozens to hundreds of managed devices	4 cores	8 GB	12 GB
Max	Enterprise, multi-site, high concurrency	8 cores	16 GB	24 GB+
Dev	Local development with hot-reload	2 cores	4 GB	6 GB

Tip

Each Gunicorn worker holds roughly 300-375 MB of resident memory. With the default WEB_CONCURRENCY=2 the API container alone needs about 1 GB. If you raise WEB_CONCURRENCY, raise API_MEM_LIMIT proportionally: API_MEM_LIMIT >= WEB_CONCURRENCY × 0.375 GB + 0.25 GB.

Disk

Volume	Minimum	Notes
Docker images + build cache	10 GB	Rebuilt containers can temporarily double this during docker compose build
postgres_data	10 GB	Scales with device count, audit log volume, and credential store
logdb_data	10 GB	TimescaleDB (syslog, SNMP traps, NetFlow, time-series health data); grows with log ingestion rate - monitor and configure retention policies
pg_backups	2× daily dump size × 7 days	Encrypted GPG dumps; set a separate disk or bind-mount for this volume in production
All other volumes	2 GB	redis_data, caddy_data, fabric_artifacts, evidence_data, agent_releases

Use an SSD for postgres_data and logdb_data. Spinning-disk latency causes excessive lock waits under the async SQLAlchemy pool.

Ports

Only the edge container (Caddy by default) publishes host ports. All data-tier ports (Postgres, Valkey/Redis, the API) are on an internal Docker network and are not accessible from the host by default.

Caddy’s internal listen ports depend on CADDY_SITE_ADDRESS:

• :80 (the Lite default) - Caddy binds only port 80 and serves plain HTTP. Port 443 is not opened inside the container; the EDGE_HTTPS_PORT mapping exists in the compose file but is a no-op in this mode.
• localhost or 127.0.0.1 - Caddy binds both 80 and 443, terminating HTTPS with its internal CA (no domain required).
• A domain name (e.g. freesdn.example.com) - Caddy binds both 80 and 443, obtaining and renewing a Let’s Encrypt certificate automatically.

The host port it binds to is controlled by EDGE_HTTP_PORT and EDGE_HTTPS_PORT in your tier’s env file:

Tier	Host HTTP port (EDGE_HTTP_PORT)	Host HTTPS port (EDGE_HTTPS_PORT)
Lite	8080	8443 (mapped but unused in default :80 mode)
Pro	80	443
Max (example default)	80	443

You can override these values in your .env.* file at any time.

Container port	Service	Required	Notes
80 → host EDGE_HTTP_PORT	Caddy edge (HTTP)	Yes	In HTTPS modes, also needed for the ACME HTTP-01 challenge. In :80 mode this is the only port Caddy uses.
443 → host EDGE_HTTPS_PORT	Caddy edge (HTTPS)	Conditional (HTTPS mode only)	Unused when CADDY_SITE_ADDRESS=:80. Required when using a domain name (Let’s Encrypt) or localhost (internal CA).

Caution

Do not expose Postgres (5432), Valkey (6379), or the API (8000) directly to the internet. The compose file binds all internal services to the Docker network only. If you need direct DB access for operations, run a shell inside the container (docker compose exec postgres psql …).

When running behind a corporate firewall or cloud security group, open the host HTTPS port (and the host HTTP port for Let’s Encrypt renewals) inbound; no other port is needed for normal user traffic. For Pro/Max domain deployments this is 443/80; for Lite homelab installs it is 8443/8080.

Supported architectures

Architecture	Status
linux/amd64 (x86-64)	Production-supported
linux/arm64	Builds and runs; tested on Apple Silicon (Docker Desktop) and Raspberry Pi 5. Not battle-tested in production.

Multi-arch images are not currently published to a public registry. You build the images from source with docker compose build using the repo’s Dockerfiles.

Network access from the host to managed devices

The FreeSDN API containers make outbound HTTPS (and, for some adapters, other vendor-specific ports) calls to managed controllers, cameras, PBX systems, and hypervisors. The host’s Docker bridge network must have IP routing to these devices. Confirm before deploying:

# From the host  -  check that your Omada controller is reachable
curl -kfsS https://<controller-ip>:<port>/api/info

If the host is behind NAT or a strict egress firewall, open outbound rules for the port ranges used by your adapters (Omada 8043 (controller REST API default), OPNsense 443, Hikvision 80/443, etc.).