Quickstart

This page walks you from zero to a running FreeSDN instance using the Lite tier - the path for a homelab or evaluation. Deployment Tiers describes resource presets, not an enterprise support commitment.

Evaluation candidate, not a production release

The prepared 26.10.0 candidate remains Community / Early Access and is qualified only on Linux amd64. ARM64 and enterprise-stable deployment are not qualified. A version in source or a passing local test does not mean a release is published. Use the instructions and release notes from the exact reviewed checkout. This page is for a fresh, disposable installation, not an existing-site upgrade.

Prerequisites

Requirement	Minimum
Docker Engine and Compose plugin	Maintained versions with security updates; use docker compose, not legacy docker-compose
Python on the host	Python 3, required by the installer configuration helper
CPU / RAM / disk	Budget source builds, running services, retained images, databases and recoverable backups separately; see Host Requirements
Qualified candidate platform	Linux amd64 (x86-64); a native Linux filesystem that can enforce private file permissions

Tip

On Linux, add your user to the docker group to run Compose without sudo:

sudo usermod -aG docker $USER

Log out and back in for the change to take effect. Membership grants control of the Docker daemon and effectively root-level host access; grant it only to trusted administrators.

1. Clone the repository

git clone https://github.com/freesdn/freesdn.git
cd freesdn

Review the selected release notes and check out the intended existing release tag before installing. Do not assume the default branch or a candidate version is a stable release, and do not invent a tag for the prepared candidate.

2. Run the installer (recommended)

install.sh configures a tier and builds the application images from source. For a named domain with automatic HTTPS, first provision DNS and the required inbound ports, then substitute your own domain and operator email:

./install.sh --tier lite --domain freesdn.example.com --email operator@example.com

The default ./install.sh uses the Lite template’s plain HTTP mapping on port 8080. Keep that mode restricted to disposable local evaluation or a reviewed upstream TLS terminator. Production/staging authentication uses Secure cookies: use an HTTPS browser origin for remote access. Do not disable cookie security or switch the backend to development mode to make remote HTTP login work. For an isolated local-CA setup, see Networking and TLS and the port/origin notes below.

The installer copies the right .env.<tier>.example to .env.<tier>, generates strong random secrets, then runs docker compose --env-file .env.<tier> build followed by docker compose --env-file .env.<tier> up -d. The first build compiles the backend and frontend images from source and takes several minutes.

2 (alternative). Manual Compose path

For a fresh installation, use the same configuration helper without starting services. It creates a private mode-0600 file with random secrets and preserves existing credentials if the file already exists:

python3 scripts/install_config.py --tier lite --domain freesdn.example.com --email operator@example.com

Review .env.lite privately. Do not commit it or paste its contents into a bug report. The helper refuses files or filesystems that cannot enforce its ownership and permission checks. If you manually provision additional secrets, generate independent values with:

python3 -c "import secrets; print(secrets.token_urlsafe(48))"

Set at minimum:

Variable	Purpose
SECRET_KEY	Application/vault key material and legacy JWT fallback; strong, non-default and preserved with existing encrypted data
JWT_SIGNING_KEY	Optional independent authentication signing key; recovery requires a coordinated new key on all target backend processes, without rotating vault keys
ENCRYPTION_SALT	Fernet credential encryption salt
POSTGRES_PASSWORD	Primary database password
LOGDB_PASSWORD	TimescaleDB (metrics) password (Compose assembles the full connection URL from this)
REDIS_PASSWORD	Valkey cache / broker password

The app refuses to boot with default secrets

FreeSDN will not start in production or staging mode unless every required secret is set to a strong, non-default value. There is no default password to bypass.

Configure encrypted backups separately; a running pg-backup container does not mean encryption, off-site transfer or recoverability is configured. Read Backups and Restore before retaining useful data.

For this fresh installation, build the source images and then start the stack:

docker compose --env-file .env.lite build
docker compose --env-file .env.lite up -d

Do not use this sequence to replace an existing installation; follow the coordinated upgrade procedure instead.

3. Watch the boot sequence

docker compose --env-file .env.lite logs -f api

The first boot initializes fresh databases and runs the candidate’s normal startup checks. Wait for the actual services and backend readiness, not only a running container or the edge’s static /healthz endpoint. A startup refusal is not permission to force-stamp the database revision or delete volumes.

4. Open the web UI

For the domain command above, use https://freesdn.example.com after DNS and certificate issuance succeed. The installer sets host ports 80/443 and matching public/browser origins for that domain.

With the unchanged Lite template, CADDY_SITE_ADDRESS=:80 serves only HTTP at http://localhost:8080; the 8443 mapping does not itself enable TLS. Changing CADDY_SITE_ADDRESS=localhost enables the internal CA, but Lite still maps HTTPS to 8443 unless EDGE_HTTPS_PORT is changed. Use https://localhost:8443 and configure the matching public/browser origin and CORS origin. Trust only the root certificate from your own fixture, after verifying its origin; never trust an arbitrary downloaded CA or use a browser security bypass.

A localhost certificate does not identify a remote VM’s IP address or LAN hostname. For remote access, configure a hostname and a certificate that matches it. See Networking and TLS.

The edge exposes these paths:

Path	What
/	React SPA
/api/v1/	REST API (JSON)
/api/v1/docs	Swagger UI (dev tier only - disabled when ENVIRONMENT=production)
/api/v1/redoc	ReDoc (dev tier only - disabled when ENVIRONMENT=production)

API docs are disabled in production

ENABLE_DOCS=1 alone is not enough. The backend gate is ENABLE_DOCS AND ENVIRONMENT != "production". All three production tiers (Lite, Pro, Max) set ENVIRONMENT=production in their env templates, so Swagger and ReDoc are unconditionally off. To access the docs, run the dev tier (ENVIRONMENT=development) - which also enables hot-reload and relaxed secret validation. Never expose the dev tier publicly.

5. First-run admin wizard

There is no default admin password. On first boot FreeSDN presents a web wizard that creates the initial super-admin account. Follow the wizard to:

1. Set the admin email and password (minimum 12 characters).
2. Name your first Organization.
3. Choose which modules to enable for your organization.
4. Add your first controller (IP/hostname and adapter type).

(The wizard also runs automated Welcome and Database health-check steps before these.)

Once the wizard completes you land on the main dashboard. To invite additional users, go to Administration → Users after setup.

6. Add your first site and controller

1. Overview → Sites - create a Site (e.g. “Main Office”).
2. Credentials - store the username/password for your first controller.
3. Controllers - point FreeSDN at your controller’s IP or hostname and select the adapter (e.g. Omada, OPNsense).
4. Enable the modules your site needs (Network, Cameras, etc.) under Settings → Modules.

FreeSDN discovers devices registered in that controller on the next sync cycle.

Stopping and upgrading

To stop this evaluation while preserving its volumes:

docker compose --env-file .env.lite down

An upgrade is not a generic fetch/build/restart operation. The database runtime stays on Debian, so a 26.09.0 volume is adopted in place, but the HA cache topology did change. Retain the old images, configuration and volumes, verify encrypted backups in isolation, and follow the database transition and coordinated application cutover from the exact target checkout. Never use down -v for an upgrade or attempt a blind application downgrade after accepting new writes.

Source builds remain the distribution path. Pre-built application images, signatures and provenance must be verified independently when they are actually published; a local image ID or version string does not establish publication.

Next steps

Goal	Where to go
Plan evaluation resources	Deployment Tiers
Understand the data model	Concepts
Configure TLS / domain	Configuration
Enable cameras or HA	Deployment Tiers
Set up roles and access	Roles and Permissions