Installing a Self-Hosted Server

Requirements

• Docker Engine 20.10 or later
• Docker Compose V2

1. Download the compose file

curl -O https://raw.githubusercontent.com/scanopy/scanopy/refs/heads/main/docker-compose.yml

2. Review the configuration

The compose file includes:

• Scanopy server on port 60072
• PostgreSQL database
• Integrated daemon for immediate network scanning

The integrated daemon needs no configuration. When you register the first user, the server provisions the integrated daemon once, giving it a site and an API key, and the daemon starts scanning. The daemon stores that identity in the daemon-config volume, so keep the volume when you recreate containers. The server reaches the daemon at http://host.docker.internal:60073, which the compose file maps to the Docker host with host-gateway. To run without the integrated daemon, remove the daemon service and clear SCANOPY_INTEGRATED_DAEMON_URL.

Docker Desktop on macOS and Windows can't run the integrated daemon, because the daemon needs host networking to see your network. Run the server in Docker, remove the daemon service, and install the daemon natively on the host. See Limitations.

3. Configure SMTP (optional)

Scanopy uses email for account recovery, security notifications, and operational alerts. SMTP is optional — the app is fully usable without it (when no email service is configured, new accounts are auto-verified, so users can register and sign in normally) — but we recommend configuring it for any multi-user deployment.

Works without SMTP

• Registration and sign-in work normally.
• You can still invite teammates: the invite screen generates a shareable link you copy and send yourself. SMTP only adds the convenience of having Scanopy email the invite for you.

Requires SMTP

• Password reset — recovery is email-only. Without SMTP, a user who forgets their password has no self-service way back in, so this is the main reason to set it up.
• Security notifications — alerts when a password or email address changes, or an SSO provider is linked or unlinked.
• Operational alerts — warnings when a daemon becomes unreachable or is placed on standby, plus per-scan discovery summaries.
• Release emails — the notes for a new version, sent once after you upgrade. See Release notes after an upgrade.

The variables are listed with an example under SMTP Configuration.

Put the SCANOPY_SMTP_* variables in the .env file next to the compose file, creating it if it isn't there. The compose file passes .env through to the server.

4. Review recommended settings

Set these in the same .env file before the first start:

SCANOPY_PUBLIC_URL=http://your-server:60072
POSTGRES_PASSWORD=a-strong-password

SCANOPY_PUBLIC_URL is the address in invite and password-reset links. Set it to the address your users reach the server at; the compose file defaults to http://localhost:60072. POSTGRES_PASSWORD sets the database password, which defaults to password. The compose file builds the server's database URL from it. PostgreSQL reads it only when it creates the database on the first start, so changing it afterwards means changing the password inside PostgreSQL as well.

• HTTPS. When a reverse proxy serves the UI over HTTPS, set SCANOPY_USE_SECURE_SESSION_COOKIES=true. To have login rate limits and auth logs see each client's address instead of the proxy's, set SCANOPY_CLIENT_IP_SOURCE to the header your proxy writes it to. The server rejects any API request without that header, so set it only when every request reaches the server through the proxy. The integrated daemon connects to the server directly, so leave it unset if you run the integrated daemon. See Reverse Proxy.
• Snapshot retention. The server keeps topology snapshots for 90 days and deletes older ones once a day. SCANOPY_SNAPSHOT_RETENTION_DAYS_OVERRIDE sets a different number of days. See Snapshot Retention.
• Registration. A Community, Self-Hosted Standard or Self-Hosted Plus server holds one organization, so once you register, anyone else needs an invite to sign up. SCANOPY_SERVER_ADMIN_CONTACT_EMAIL sets the address shown to people turned away. An Enterprise server holds any number of organizations, and anyone who can reach it can register and create one. Set SCANOPY_DISABLE_REGISTRATION=true to accept only invited users.
• Update check. Twice a day the server asks api.github.com for the latest release and shows admins a banner when an upgrade is out. SCANOPY_DISABLE_UPDATE_CHECK=true turns the check off.

5. Start Scanopy

docker compose up -d

6. Verify the installation

Check that services are running:

docker compose ps

The server and postgres services should show as running, and daemon too if you kept the integrated daemon.

If the image pull fails, see Docker Pull or Download Fails. If any service fails to start, check its logs with docker compose logs <service-name> and open an issue with the output.

7. Open the UI

Navigate to http://<your-server-ip>:60072

You'll see the registration page on first load. Your server keeps its own accounts, separate from Scanopy Cloud, so register a new one here. A Scanopy Cloud login doesn't work on it.

Install on Unraid

Unraid's Community Applications list scanopy-server and scanopy-daemon, community-maintained templates that run the same ghcr.io images as the compose file. The server needs a PostgreSQL database you provide: point SCANOPY_DATABASE_URL in the scanopy-server template at it.

Run the compose stack on Proxmox

If you run the compose stack in an LXC, you may need to change SCANOPY_INTEGRATED_DAEMON_URL to 172.31.0.1. See issue #87. Running directly on a Proxmox host can also fail with could not create any Unix-domain sockets. See Troubleshooting.

Uninstalling

# Stop and remove containers
docker compose down

# Remove volumes (deletes all data)
docker compose down -v

# Remove images
docker compose down --rmi all

Next Steps

• Server Configuration — Configure server settings
• Configuring Single Sign-On (OIDC) — Set up enterprise authentication
• Quick Start — Deploy your first daemon