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	Candidate qualification boundary
Docker Engine	Use a maintained Engine with current security updates. The September 26 qualification VM runs Engine 29.8.1; older-version compatibility has not been established by that run.
Docker Compose	Use the docker compose plugin. The qualification VM runs 5.5.1; a check that insists the version start with v2 would incorrectly reject it. Legacy docker-compose v1 is not supported.
Operating system / architecture	Linux amd64 / x86-64 for the appliance candidate, on a filesystem that enforces Unix ownership and private mode-0600 configuration.
Python on the host	Python 3 is required by the installer configuration helper. Backend Python and application dependencies are built into the images; installing them globally on the host is unnecessary.

Qualification is not a production support promise

The prepared candidate remains Community / Early Access. Linux amd64 is the qualified appliance architecture. macOS, Windows/WSL, rootless Docker and ARM64 are not qualified production targets by this evidence. Development use on those platforms does not establish appliance support. The observed tool versions above record a tested host; they are not a perpetual claim about the latest releases.

Database and broker maintenance prerequisites

Valkey and the host memory policy

On Linux, check the host setting before deployment:

sysctl vm.overcommit_memory

Valkey recommends vm.overcommit_memory = 1 so that its fork-based persistence can start without Linux requiring space for a complete second copy of the process. Review this host-wide allocation policy with the host administrator. On a dedicated host where that change is appropriate, apply it with sudo sysctl -w vm.overcommit_memory=1 and persist the same setting through the host’s managed /etc/sysctl.d/ configuration. Do not overwrite an existing policy or change a shared host silently. Check the value again after a reboot. FreeSDN’s installer does not make this privileged host change for you.

This setting does not supply more RAM or prevent an out-of-memory failure. Keep the container budgets, broker memory limit and host headroom under observation; persistence can use additional memory while pages change during a save. See Valkey’s persistence explanation.

TimescaleDB scheduled policies

A database accepting connections does not prove that compression, retention or aggregate refresh jobs can run. The September 26 maintenance qualification candidate sets max_worker_processes = 32 in docker/postgres/logdb-custom.conf. This accommodates the configured 16 TimescaleDB background slots, eight parallel-query slots and additional worker headroom. It is a ceiling on slots, not 32 permanently busy processes. Older releases may still have PostgreSQL’s eight-slot default; inspect the actual checkout and database settings.

The configuration is mounted read-only by Compose. Changing this parameter requires a planned LogDB restart, not just a configuration reload. Do not change memory or concurrency limits without measuring the resulting workload. After installation or recovery, inspect timescaledb_information.jobs together with timescaledb_information.job_stats: the four application compression policies, four retention policies and three aggregate-refresh policies should be enabled and should report successful executions. Investigate failures or jobs that have never run instead of relying only on pg_isready.

The candidate’s isolated acceptance check now requires successful executions of all eleven application policies. This small synthetic check does not establish retention performance, recovery objectives or capacity for your device fleet.

CPU and RAM by tier

The numbers below are planning starting points, not measured fleet capacities or acceptance guarantees. Check the exact checkout’s container limits, reserve headroom for source builds and backups, and measure your own workload. A Max preset is not an enterprise certification.

Tier	Planning use case	Starting CPU	Starting RAM	Additional RAM headroom
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

Raising WEB_CONCURRENCY or Celery concurrency increases memory demand. Review API_MEM_LIMIT, worker budgets and measured cgroup peaks together. Do not assume an old per-worker RSS estimate is valid for the current dependencies or enabled modules. A container memory limit is a ceiling, not a reservation or a capacity measurement.

Disk

Budget all of these separately:

Storage	Budget considerations
Source builds and images	Include temporary layers, compiler downloads, build cache, and both the old and candidate images. A blanket 10 GB free-space claim does not cover release builds and rollback retention.
Primary database	Inventory, vault, authorization, schedules and audit history; measure growth and index maintenance space.
LogDB	Event and time-series ingestion, chunks, indexes and the configured retention window.
Backups	Completed encrypted pairs, temporary archive space, off-site staging and the chosen retention window. A dump count alone does not establish recoverability.
Application and broker volumes	Report archives, queue state, CA data, artifacts, media and any enabled optional profiles.
Recovery	Isolated target databases and application files in addition to retained source volumes and images.

Use monitored storage with enough free space for the next build or restore as well as normal growth. The internal qualification pipeline uses its own explicit free-space guards; those thresholds are not universal installation minimums. Prefer SSD-backed databases and test latency and I/O under your intended load. Do not remove existing volumes or unverified recovery evidence to make space.

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. Restrict it to local evaluation or a reviewed upstream TLS terminator; browser authentication in production/staging uses Secure cookies and remote access needs HTTPS. 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. The client must trust that specific CA and use a matching certificate name; a localhost certificate does not authenticate a remote VM’s LAN name or IP.
• 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)	Prepared candidate qualification only; Community / Early Access, no enterprise-stable claim
linux/arm64	Not qualified for this candidate; do not treat development builds as a supported appliance release

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:

Validate the intended controller hostname, route, port and certificate chain with your own lab CA where required. Do not disable TLS verification as a normal setup step or assume an arbitrary API path exists on every firmware. Use operation-specific read-only acceptance before enabling writes, and keep lab credentials out of shared logs.

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.).