Quickstart

This page walks you from zero to a running FreeSDN instance using the Lite tier - the fastest path for a homelab or evaluation. For production sizing see Deployment Tiers.

Prerequisites

Requirement	Minimum
Docker Engine	26+
Docker Compose plugin	v2.24+
RAM	2 GB free (Lite tier)
Disk	10 GB free
OS	Linux, macOS, or Windows with WSL2

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.

1. Clone the repository

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

2. Run the installer (recommended)

install.sh is a tier-aware one-command bootstrapper. For a local HTTP instance:

./install.sh

For a named domain with automatic HTTPS via Let’s Encrypt:

./install.sh --tier pro --domain freesdn.example.com

The installer copies the right .env.<tier>.example to .env.<tier>, generates strong random secrets, and runs docker compose --env-file .env.<tier> up -d.

2 (alternative). Manual Compose path

If you prefer full control over the env file:

cp .env.lite.example .env.lite

Open .env.lite and set the required secrets. Generate strong values with:

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

Set at minimum:

Variable	Purpose
SECRET_KEY	JWT signing key (≥ 32 characters, non-default)
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.

Bring it up:

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

3. Watch the boot sequence

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

The API worker reports all services healthy and begins listening. The first boot runs database migrations automatically.

4. Open the web UI

The Lite tier defaults to plain HTTP on port 8080:

http://localhost:8080

To use port 80 instead, set EDGE_HTTP_PORT=80 in your .env.lite (requires running as root or with CAP_NET_BIND_SERVICE).

Set CADDY_SITE_ADDRESS=localhost to get HTTPS via Caddy’s internal CA:

https://localhost

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

# Stop without removing volumes
docker compose --env-file .env.lite down

# Pull the latest images and restart
docker compose --env-file .env.lite pull
docker compose --env-file .env.lite up -d

Next steps

Goal	Where to go
Size for production	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