On-Premise Installation Guide

1. Prerequisites

Make sure the following are installed on your server:

Quick Docker install (Ubuntu/Debian):

curl -fsSL https://get.docker.com | sh

Inbound Ports

Connections coming into the server. Your NAS/gateway and (if used) the syslog source must be able to reach these.

The database port (5432) is not exposed — it is only reachable on the internal container network.

Outbound Rules

If you use these integrations, allow outbound connections from the server. On a restricted (deny-all outbound) network, only open the rows you actually use.

2. Installation (Single Command)

The recommended path installs from Docker Hub: the images are public. You clone a small deploy repo and run the install script with a single command. For networks with no internet access, use the air-gapped (offline) alternative in §9.

2.1 Clone the Deploy Repo

A deploy package (captivo.io/onprem) contains only the docker compose file and install script — no source code. This is where install.sh comes from:

curl -fsSL https://captivo.io/onprem/captivo-onprem.tar.gz | tar xz
cd captivo-onprem

2.2 Run the Install Script

chmod +x onprem/install.sh
./onprem/install.sh

The script asks for the server address during installation and auto-suggests your LAN IP. If you'll use a domain with automatic HTTPS, see the TLS section.

The script:

1. Checks for docker and openssl dependencies.
2. Generates .env.onprem with all secrets (POSTGRES_PASSWORD, AUTH_SECRET, DATA_ENCRYPTION_KEY, etc.) randomly generated via openssl rand.
3. Runs docker compose pull to pull the public images from Docker Hub, then up -d to start them.
4. The migrator service applies the database schema.
5. Prints the panel URL when done.

Docker Hub Images

The following images are public and pulled automatically by docker compose pull:

Example output:

2.3 Updating

To move to a new version — your data and .env.onprem are preserved:

docker compose -f docker-compose.onprem.yml --env-file .env.onprem pull
docker compose -f docker-compose.onprem.yml --env-file .env.onprem up -d
docker image prune -f   # clean old (untagged) image layers

Every update leaves the previous images untagged, accumulating ~1-2 GB per release; left uncleaned, the disk eventually fills up and a future update can fail halfway.docker image prune -f only removes untagged layers — it never touches running containers or freshly pulled images.

The migrator applies new schema changes automatically and additively; the database and secrets are unchanged. A destructive schema change (rare) safely halts the update to prevent data loss — follow the manual steps in that release's notes if it occurs.

3. First Launch — Setup Wizard

The first time you open the panel (http://<server-ip>:3000), you will be automatically redirected to the /setup wizard. It has 10 steps:

4. TLS / HTTPS (Recommended for Production)

The default http://localhost:3000 is for local testing only. HTTPS is required in production.

4.1 Configure Your Domain

Edit .env.onprem:

NEXTAUTH_URL=https://wifi.company.com
SITE_DOMAIN=wifi.company.com

4.2 Start Caddy with the TLS Profile

docker compose -f docker-compose.onprem.yml \
  --profile tls \
  --env-file .env.onprem \
  up -d

4.3 TLS with a Corporate CA (Closed Network / Internal FQDN)

On a closed network with an internal domain (e.g. captivo.acme.local), Let's Encrypt cannot be used. Instead you present Caddy with a certificate issued by your organization's own CA (e.g. AD CS).

1. Issue a server-auth certificate whose SAN is your internal FQDN (corporate CA / AD CS). You need two files: cert.pem(server certificate + intermediate chain) and key.pem(unencrypted private key). Place both files in onprem/certs/ on the server.
2. Edit .env.onprem:

SITE_DOMAIN=captivo.acme.local
CADDY_TLS_BLOCK=tls /certs/cert.pem /certs/key.pem

Then start the services with the --profile tlscommand from §4.2. (If CADDY_TLS_BLOCK is left empty, Caddy attempts automatic ACME; tls internalis for testing only — devices won't trust it.)

5. RADIUS — Connecting Your NAS

The FreeRADIUS container starts automatically and listens on UDP 1812/1813. Configure the following on your NAS or gateway device:

Supported NAS/gateway models: pfSense, OPNsense, MikroTik, FortiGate, Cisco Meraki, UniFi, Ruijie, and other devices supporting PAP/CHAP.

6. 5651 Log Server (Optional)

The captivo-logd service collects traffic logs (syslog) from your firewall, correlates them with guest identity via RADIUS, signs them daily, and retains them for 2 years as required by Turkish Law No. 5651 — after which they are auto-deleted for KVKK (data-protection) compliance. This is an optional module — enable it for deployments with a 5651 log obligation.

6.1 Enable the Service

The log service listens on port 514 (UDP/TCP). Point your firewall's syslog output to this server:

6.2 Review in the Panel

Collected logs are managed in the panel under Settings → Log Server:

• •Sources — lists the firewalls sending logs
• •Search — query logs with the correlated guest identity
• •Signed archive — daily signed log bundles
• •Verify — verify archive integrity
• •Settings — retention period and other parameters

7. Licence

8. Backups

Database Backup

onprem/backup.sh runs pg_dump from PostgreSQL, compresses the output and stores it (7-day rotation).

Run manually:

POSTGRES_USER=captivo BACKUP_DIR=/opt/captivo-backups \
  ./onprem/backup.sh

Schedule with cron (daily at 03:15):

15 3 * * * POSTGRES_USER=captivo BACKUP_DIR=/opt/captivo-backups \
  /opt/captivo-onprem/onprem/backup.sh >> /var/log/captivo-backup.log 2>&1

Application Scheduled Jobs (Optional)

Some features run on a periodic trigger: scheduled reports, MAC whitelist expiry, KVKK/5651 retention cleanup, session webhooks, and the SMS anomaly alert. To use them, add a CRON_SECRET to .env.onprem(e.g. openssl rand -hex 32), restart the container, and add the cron lines below:

# Session webhooks (session.started/ended) — if accounting is on; every minute
*/1 * * * *  curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/session-events       >> /var/log/captivo-cron.log 2>&1
# MAC whitelist expiry — hourly
10 * * * *   curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/mac-whitelist-expiry >> /var/log/captivo-cron.log 2>&1
# Scheduled reports — hourly
0 * * * *    curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/scheduled-reports    >> /var/log/captivo-cron.log 2>&1
# KVKK/5651 retention cleanup — daily
30 3 * * *   curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/kvkk-retention       >> /var/log/captivo-cron.log 2>&1
# SMS usage anomaly — every 15 minutes
*/15 * * * * curl -sS -X POST -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/sms-anomaly          >> /var/log/captivo-cron.log 2>&1

9. Air-Gapped (Offline) Installation

For networks with no internet access, instead of pulling from Docker Hub the images can be pre-packaged into a .tar file and transferred to the target server. This is the offline alternative to the Docker Hub path in §2.

Bundle on an internet-connected machine

# Bundle the latest release
./scripts/onprem/build-offline-bundle.sh

# For a specific version:
./scripts/onprem/build-offline-bundle.sh 1.0.0

Output: captivo-onprem-1.0.0.tar (includes web, RADIUS, logd, postgres and caddy images)

Install on the target machine

# Load images into Docker
docker load -i captivo-onprem-1.0.0.tar

# Run the install script (no internet needed)
./onprem/install.sh

10. Troubleshooting

# All service logs (last 50 lines)
docker compose -f docker-compose.onprem.yml \
  --env-file .env.onprem \
  logs --tail=50

# FreeRADIUS logs
docker logs captivo-radius