Installing Scanopy (Self-Hosted)

Deploy the Scanopy server on your own infrastructure with Docker Compose.

On a commercial plan? See Deploying the Commercial Edition for the license-gated server image instead of the steps below.

Requirements

Docker Installation (Recommended)

Docker Engine 20.10 or later
Docker Compose V2

Running Without Docker (see below)

Linux on x86_64 or arm64
PostgreSQL 17
4GB RAM minimum
20GB disk space

No Rust or Node toolchain is needed — the server binary is prebuilt and self-contained.

Docker Installation (Recommended)

This is the easiest way to get started with self-hosted Scanopy.

1. Download the Docker Compose File

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

2. Review Configuration

The default docker-compose.yml includes:

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

You don't need to configure anything for the integrated daemon to work; the server will auto-initialize it when the container is started and it will immediately begin scanning. If you don't want to run a daemon in the same container as the server, remove the daemon service and clear the SCANOPY_INTEGRATED_DAEMON_URL env var.

Important: The integrated daemon assumes your Docker bridge network is 172.17.0.1. If your Docker bridge uses a different address, edit the SCANOPY_INTEGRATED_DAEMON_URL environment variable in the compose file.

3. Start Scanopy

docker compose up -d

4. Verify Installation

Check that services are running:

docker compose ps

All three services should show as running: scanopy-server, scanopy-postgres, and scanopy-daemon.

If any service fails to start, check its logs with docker compose logs <service-name> and open an issue with the output.

5. Access the UI

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

You'll see the registration page on first load.

Platform-Specific Instructions

Proxmox LXC Container

You can use this helper script to create a Scanopy LXC on your Proxmox host.

Unraid

Scanopy is available as an Unraid community app.

Common Issues:

If running Scanopy directly on a Proxmox host and encountering could not create any Unix-domain sockets, add this to both the PostgreSQL and Scanopy services in your docker-compose:

security_opt:
  - apparmor:unconfined

If running in an LXC, you may need to change SCANOPY_INTEGRATED_DAEMON_URL to 172.31.0.1.

See issue #87 for more details.

Running Without Docker

The server ships as a single self-contained binary: migrations and the web UI are compiled in, so there is nothing to place beside it and no build step. Postgres is the only thing it needs.

1. Download the binary

sudo useradd --system --home /opt/scanopy --shell /usr/sbin/nologin scanopy
sudo mkdir -p /opt/scanopy

# Use scanopy-server-linux-arm64 on arm64 hosts
sudo curl -L -o /opt/scanopy/scanopy-server \
  https://github.com/scanopy/scanopy/releases/latest/download/scanopy-server-linux-amd64
sudo chmod +x /opt/scanopy/scanopy-server
sudo chown -R scanopy:scanopy /opt/scanopy

The binaries are statically linked against musl, so they run on any glibc or musl distribution — Debian, RHEL, Alpine — with no runtime dependencies to install.

2. Create the database

Scanopy needs a PostgreSQL 17 database. On Debian:

sudo apt install postgresql
sudo -u postgres createuser --pwprompt scanopy
sudo -u postgres createdb --owner=scanopy scanopy

The server creates its own schema on first start and applies pending migrations on every start, so there is no manual schema step — on install or on upgrade.

3. Configure the server

Every setting is a SCANOPY_* environment variable. There is no config file, and nothing is Docker-specific: the same variables that appear in a compose file work identically here. Set them however your setup allows — a systemd EnvironmentFile (recommended below), a .env file in the server's working directory, or a plain shell export.

Only SCANOPY_DATABASE_URL is strictly required. SCANOPY_PUBLIC_URL is used in invite and password-reset links, so set it to the address your users reach the server at.

sudo mkdir -p /etc/scanopy
sudo tee /etc/scanopy/server.env >/dev/null <<'EOF'
SCANOPY_DATABASE_URL=postgresql://scanopy:your-password@localhost:5432/scanopy
SCANOPY_PUBLIC_URL=http://your-server:60072
SCANOPY_LOG_LEVEL=info
EOF
sudo chown scanopy:scanopy /etc/scanopy/server.env
sudo chmod 600 /etc/scanopy/server.env

Commercial plans add SCANOPY_LICENSE_KEY to that same file — see Deploying the Commercial Edition.

4. Run it under systemd

Create /etc/systemd/system/scanopy-server.service:

[Unit]
Description=Scanopy Server
After=network.target postgresql.service

[Service]
Type=simple
User=scanopy
WorkingDirectory=/opt/scanopy
EnvironmentFile=/etc/scanopy/server.env
ExecStart=/opt/scanopy/scanopy-server
Restart=on-failure

[Install]
WantedBy=multi-user.target

EnvironmentFile is preferred over a .env file because it does not depend on which directory the service happens to start in.

sudo systemctl daemon-reload
sudo systemctl enable --now scanopy-server
sudo systemctl status scanopy-server

Then access the UI at http://<your-server-ip>:60072, same as the Docker install. Reload configuration changes with sudo systemctl restart scanopy-server.

5. Add a daemon

No daemon is bundled with the server binary, so install one separately: download the daemon release binary for your platform and enrol it against the server. See Setting Up Daemons.

To reproduce the Docker stack's zero-config integrated daemon, start a daemon on the same host listening on port 60073 before you register the first user, and set SCANOPY_INTEGRATED_DAEMON_URL=http://127.0.0.1:60073. The server provisions that daemon during first-user registration — setting the variable later has no effect on a deployment that already has an account. Leave it unset otherwise.

Uninstalling

Docker Installation

# Stop and remove containers
docker compose down

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

# Remove images
docker rmi ghcr.io/scanopy/scanopy/server:latest
docker rmi ghcr.io/scanopy/scanopy/daemon:latest

Native Installation

sudo systemctl disable --now scanopy-server
sudo rm /etc/systemd/system/scanopy-server.service
sudo systemctl daemon-reload
sudo rm -rf /opt/scanopy /etc/scanopy

# Drop the database (deletes all data)
sudo -u postgres dropdb scanopy

Next Steps

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

Installing Scanopy (Self-Hosted)

On this page