First-run Setup

The first time FreeSDN starts after a clean deploy, every request to the application is redirected to /setup. That route stays open (no login required) until the super-admin account is created in Step 3. The moment POST /setup/admin succeeds and a super_admin row exists in the database, the backend gate (require_setup_incomplete) closes and every subsequent /setup/* write endpoint returns 403 Forbidden. Finalize (Step 6) marks the wizard as done in the UI and navigates you to /login (a client-side navigation, not a server-side redirect); the 403 enforcement is what prevents anyone from re-running setup after Step 3.

This page walks you through each step in order, explains the deliberate ordering decisions, and covers what to do immediately after the wizard finishes: creating additional organizations, inviting users, and adjusting module enablement.

Before you begin

Complete the deployment steps first: set all required environment variables (SECRET_KEY, ENCRYPTION_SALT, POSTGRES_PASSWORD, LOGDB_URL, REDIS_PASSWORD), bring the stack up, and verify the containers are healthy. The setup wizard will not let you proceed past Step 1 if the database is unreachable or migrations are pending.

---

The seven-step wizard

The wizard renders a step sidebar on the left (desktop) or a drawer (mobile), a progress bar, and an environment badge (production / development) in the corner. Steps are sequential - you cannot skip ahead, but you can navigate back to review earlier inputs before submitting.

Step 0 - Welcome

The Welcome step runs a system requirements checklist and surfaces the exact version of FreeSDN you just deployed along with a collapsible summary of the backend, frontend, and Docker stack versions.

What you see:

• Pass/fail status for each requirement (Python runtime, Node version, database connectivity, etc.)
• The app version and license identifier (AGPL-3.0)
• Continue is disabled if can_proceed is false - fix any failing requirement before moving on

You do not need to enter anything here. Read the checklist and click Continue when all items are green.

Step 1 - Database

This step probes four things:

Check	Required to continue
PostgreSQL connectivity	Yes
PostgreSQL version	Informational
TimescaleDB extension (logdb)	Yes
Pending Alembic migrations	Blocking if any

If migrations are pending, a Run Migrations button appears. Click it and wait for the migration output. Both the primary database and the logdb (TimescaleDB) must report connected before Continue activates.

Do not skip pending migrations

If you skip migration errors by any workaround, later steps may create data that is incompatible with an un-migrated schema. Always run migrations before proceeding.

Step 2 - Organization

Enter your organization name and a short slug (URL-safe identifier). At this step the values are held in local wizard state only - nothing is written to the database yet.

Why Organization comes before Admin: Creating the super-admin account in Step 3 closes the setup gate in a single atomic transaction. To do that atomically, the wizard needs the organization details up front. If you entered Admin first and the request failed mid-way, you could end up with a user but no organization, or vice versa.

Field	Notes
Organization name	Shown in the UI header and org-management pages; editable later at Settings → General
Slug	Used in API scoping; lowercase alphanumeric + hyphens; not currently shown in end-user UI but must be unique

Step 3 - Admin

This step creates your super-admin account. The form collects email, username, and password.

Password requirements (enforced both client-side and server-side):

Rule	Minimum
Length	12 characters
Uppercase letters	1
Lowercase letters	1
Digits	1
Special characters	1

A live strength meter and a five-rule checklist give immediate feedback as you type. A confirm-password field must match before submission is allowed.

Clicking Create Account submits the wizard atomically: one transaction creates the super-admin user, the organization from Step 2, a default site, and the super-admin’s organization membership. If the request fails, nothing is persisted - you can correct the inputs and try again.

This is the only super_admin account

The account you create here has role = super_admin (tier 100), the highest privilege level. Treat the password accordingly. You can create additional admins later through the Users page, but you cannot create a second super_admin through the UI after setup - that operation is reserved for database-level intervention.

Step 4 - Modules

Choose which of the 9 user-facing modules to enable for your organization. You can change this at any time after setup at Settings → Modules (/settings/modules/).

Module	Default state	Notes
Network Management	On (pre-selected)	Reference adapter: Omada (gold standard)
Video Surveillance	Off	Requires camera controllers or NVRs
VoIP & Telephony	Off	Requires PBX or phone controllers
Firewall	Off	Absorbs gateway orchestration; requires a gateway controller
Access Control	Off	Beta, off by default
Backup & Restore	On (pre-selected)	Config snapshot - not full DR
AI Assistant	On (pre-selected - Beta)	Requires an AI provider credential
Observability	Off	SNMP trap / Syslog / NetFlow passive collector
Hypervisor	Off	Requires a registered Proxmox controller

Access Control and AI are beta

Access Control currently renders an API-only placeholder - door lock/unlock endpoints return 501 because no door adapter ships in this release. The AI Assistant is functional but carries governance configuration requirements before production use. Enable both advisedly.

Disabled modules disappear from the sidebar. Navigating directly to a disabled module’s URL shows a “Module Disabled” notice rather than a blank page or error. You are not deleting anything by disabling a module - data is retained and the module re-activates immediately when you re-enable it.

Step 5 - Controllers (optional)

Add your first network controller. This step is optional - you can skip it and add controllers later at /controllers/.

Supported controller types at this step: Omada, UniFi, and others surfaced by GET /setup/controllers/types.

For Omada, two connection modes are available:

Mode	Fields required
Local (direct)	Host/IP, port, username, password
Cloud	client_id, client_secret, omada_id, region

After entering credentials, click Test Connection. If the test passes, the wizard probes the remote controller for its sites (Probe Remote Sites) and shows a site-binding sub-step where you map each remote Omada site to a FreeSDN site. A default site was created in Step 3; you can bind to it or create new ones.

You must complete the site-binding before Add Controller is available. Skip the entire step if you want to configure controllers later with full access to the Controllers page UI.

Step 6 - Complete

The final step shows a summary of what will be (or was) created. Three optional toggles appear before you finalize:

Toggle	Default	What it does
Install sample data	Off	Populates placeholder sites and devices for UI exploration
Start discovery	On	Kicks off a network discovery scan on the default site immediately after setup
Send welcome email	Off	Sends an onboarding email to the super-admin address

Click Finalize to call POST /setup/complete. When the call succeeds, the page shows a Go to Login button which navigates client-side to /login. (The backend gate that blocks re-running setup closed at Step 3 when the super-admin was created - see the intro note above.)

---

After the wizard: immediate next steps

1. Log in as super_admin

Navigate to /login, enter the email and password you set in Step 3. If MFA is configured at the IdP level (OIDC), you will complete SSO before landing on the dashboard.

On first login after a password reset or rotation policy trigger, FreeSDN forces you through /change-password before you reach the dashboard.

2. Create a site (if you skipped the controller sub-step)

The wizard created one default site. If your deployment spans multiple physical locations, add sites now at /sites/ before adding controllers, because controllers bind to a site at registration time.

Procedure:

1. Open Sites in the sidebar (global “All Sites” view only).
2. Click Create Site.
3. Enter a name, optional timezone, city, and country.
4. Save - the site appears immediately in the Site Selector dropdown.

3. Register controllers

Go to /controllers/ and click Add Controller. The fields vary by controller type; refer to the Controllers guide for per-vendor instructions.

For every controller type, you can Test Connection before saving. A failed test does not block saving, but an unreachable controller will show as offline and block adapter calls.

Key API endpoints for controller management:

Method	Path	Purpose
GET	/api/v1/controllers	List all registered controllers
POST	/api/v1/controllers	Register a new controller
POST	/api/v1/controllers/{id}/test	Test connectivity
POST	/api/v1/controllers/{id}/sync	Trigger a manual sync
DELETE	/api/v1/controllers/{id}	Remove a controller

4. Invite users

Go to /users/ (sidebar Administration section, global “All Sites” mode only). You need org_admin role or higher to access this page - as super_admin you have it.

Create a user:

1. Click Invite User or Add User.
2. Enter email, username, display name, and an initial password.
3. Assign a role (see the role table below).
4. Optionally restrict the user to specific sites using the site-grant controls on the user detail page after creation.

Role hierarchy:

Role	Tier	Typical use
super_admin	100	Platform owner - cannot be assigned via UI after setup
org_admin	60	Org-level administration, cannot elevate past their own tier
site_admin	40	Administration scoped to assigned sites
operator	20	Day-to-day operations: apply changes, manage devices
viewer	10	Read-only access

Role model

The UserRole ORM enum defines exactly five assignable values: super_admin, org_admin, site_admin, operator, and viewer. The internal RBAC hierarchy dict also references admin (tier 80) and guest (tier 0) for arithmetic purposes, but those strings are not valid values for the User.role database column and cannot be assigned via the API or UI.

Role assignment ceiling

A user can only assign roles strictly lower than their own tier. An org_admin (60) cannot create another org_admin or higher. This is enforced server-side; the UI reflects it by disabling higher-tier options.

Per-user site grants: By default a user in an org can see all sites in that org (subject to their role permissions). To restrict a user to specific sites, open their detail page and add explicit site grants. This is a hybrid model - org-level role sets what actions they can take; site grants determine which sites they see.

No PostgreSQL RLS

Multi-tenancy is enforced at the application layer: queries are org-scoped in the service layer. There is no PostgreSQL Row Level Security. Do not rely on database-level isolation to separate tenants - FreeSDN’s isolation is correct but it lives in the application code, not the database engine.

5. Configure SSO (optional)

Go to Settings → SSO (/settings/sso/). FreeSDN supports:

Protocol	Status
OIDC	Working
LDAP	Working
SAML	501-gated. Not available in this release

For OIDC: enter the IdP name, discovery URL (or manual endpoints), client ID, and client secret. Save and test the IdP. Users who authenticate via OIDC land on /auth/sso/callback, which validates the state token, completes login, and routes onward.

SAML is not available

The SAML path returns 501 Not Implemented. Do not configure an IdP expecting SAML to work - it will reject all SAML authentication attempts.

6. Enable MFA for the super-admin account

Open the user menu (top-right), click your name, then Profile. MFA status is shown. Click Enable to go to the MFA setup flow where you scan a TOTP QR code and save backup codes.

Save your backup codes

Backup codes are shown once at enrollment time. If you lose access to your TOTP device and have no backup codes, account recovery requires database-level intervention.

7. Adjust module enablement

The wizard captured your initial module choices. Change them at any time at Settings → Modules (/settings/modules/). The Modules tab shows a per-module enable/disable table. Clicking a row opens the module detail page (/settings/modules/{moduleId}/) with description, version, adapter list, and reload controls.

Changes take effect immediately for new page loads. No restart is required.

---

Creating additional organizations

FreeSDN is multi-tenant. Each organization is an isolated tenant with its own sites, users, controllers, and module enablement. The organization you created in Step 2 is the first tenant. To add more:

1. Ensure you are in “All Sites” mode in the Site Selector.
2. Go to /organizations/ (sidebar Administration, gated organization:read).
3. Click Create Organization.
4. After creating the org, open its detail page to add sites, set module enablement, and invite users to that org.

Each organization independently controls which modules are active. A module enabled for org A is invisible to org B unless org B enables it separately.

---

Module enablement: what changes when you toggle a module

What changes	When a module is disabled
Sidebar nav items	Hidden (both module-gated items and any sub-items)
Direct URL access	Shows “Module Disabled” page - no error, no crash
API endpoints	Still respond, but the UI will not reach them
Data	Retained - disabling is not deletion
Re-enabling	Immediate - data and settings are restored

The enable/disable state is per-organization. The backend ModuleGuard and frontend ModuleGuard component enforce this independently.

---

Settings to review after setup

Once logged in as super-admin, work through these settings before inviting users or connecting production infrastructure:

Setting	Location	Why
Organization name and timezone	/settings/general/	Shown in UI and used for scheduled-task time display
Password policy	Backend env (PASSWORD_MIN_LENGTH etc.)	Default min 12; adjust if policy requires more
Rate limits	Backend env (RATE_LIMIT_*)	Default: 100/min general, 5/min auth
Email / SMTP	Notification provider	Required for password-reset and welcome emails
AI governance	/settings/ai/	Global kill-switch is off by default; enable only after reviewing the three-layer governance model
Backup schedule	/backups/	The backup module config-snapshots on a schedule; verify the destination storage location
Metrics auth	METRICS_AUTH_TOKEN env	/metrics is blocked without a token; set it before wiring Prometheus

---

Next steps

• Add your first devices - after controllers are registered, run discovery at /discovery/ (site-scoped).
• Understand the dashboard - see the Dashboard Overview for a map of every sidebar section and top-bar control.
• Configure automation - wire events to actions using the Fabric visual builder at /fabric/.
• Register a site agent - for L2/L3 deep discovery on remote networks, see the Agent guide.
• Review the adapter maturity matrix - before relying on a vendor adapter in production, check docs/SUPPORTED_VENDORS.md or the Supported Vendors page for its capability tier.