Server Configuration

Configuration options for self-hosted Scanopy servers.

Configuration reference for self-hosted Scanopy server deployments.

Configuration Methods

Environment variables in docker-compose:

environment:
  - SCANOPY_SERVER_PORT=60072
  - DATABASE_URL=postgresql://postgres:password@db:5432/scanopy

Command-line (for binary builds):

./scanopy-server --port 60072 --database-url postgresql://...

Parameter Reference

Parameter	CLI Flag	Environment Variable	Default	Description
Server Public URL	`--public-url`	`SCANOPY_PUBLIC_URL`	`http://localhost:60072`	Public URL for webhooks, email links, etc
Server Port	`--server-port`	`SCANOPY_SERVER_PORT`	`60072`	Port for server to listen on
Database URL	`--database-url`	`SCANOPY_DATABASE_URL`	Required	PostgreSQL connection string
Web External Path	N/A	`SCANOPY_WEB_EXTERNAL_PATH`	`/app/static`	Location from which to serve server static files
Log Level	`--log-level`	`SCANOPY_LOG_LEVEL`	`info`	Logging verbosity: `trace`, `debug`, `info`, `warn`, `error`
Secure Cookies	`--use-secure-session-cookies`	`SCANOPY_USE_SECURE_SESSION_COOKIES`	`false`	Enable HTTPS-only cookies
Integrated Daemon URL	`--integrated-daemon-url`	`SCANOPY_INTEGRATED_DAEMON_URL`	`http://172.17.0.1:60073`	URL to reach daemon in default docker compose
Disable Registration	`--disable-registration`	`SCANOPY_DISABLE_REGISTRATION`	`false`	Disable new user registration
SMTP Username	`--smtp-username`	`SCANOPY_SMTP_USERNAME`	-	SMTP username for email features
SMTP Password	`--smtp-password`	`SCANOPY_SMTP_PASSWORD`	-	SMTP password for email authentication
SMTP Relay	`--smtp-relay`	`SCANOPY_SMTP_RELAY`	-	SMTP server address (e.g., `smtp.gmail.com`)
SMTP Email	`--smtp-email`	`SCANOPY_SMTP_EMAIL`	-	Sender email address for outgoing emails
Client IP Source	`--client-ip-source`	`SCANOPY_CLIENT_IP_SOURCE`	-	Source of IP address from request headers for reverse proxy setups
Metrics Token	`--metrics-token`	`SCANOPY_METRICS_TOKEN`	-	Bearer token for Prometheus metrics endpoint authentication
Prometheus Allowed IPs	N/A	`SCANOPY_EXTERNAL_SERVICE_PROMETHEUS_ALLOWED_IPS`	-	Comma-separated IPs/CIDRs allowed to access metrics endpoint

Integrated Daemon URL

The integrated daemon runs in a separate container and needs to reach the server. The default assumes Docker's bridge network gateway is 172.17.0.1.

Check your bridge gateway:

docker network inspect bridge | grep Gateway

If different, update in docker-compose.yml:

environment:
  - SCANOPY_INTEGRATED_DAEMON_URL=http://YOUR_GATEWAY_IP:60073

SMTP Configuration

SMTP settings enable email-based features such as password reset.

All SMTP parameters are optional. If not configured, email features will be disabled.

Configuration:

environment:
  - SCANOPY_SMTP_RELAY=smtp.gmail.com
  - [email protected]
  - SCANOPY_SMTP_PASSWORD=your-app-password
  - [email protected]

UI Configuration

The UI automatically uses the hostname and port from your browser's address bar to reach the API.

No configuration needed for standard deployments where UI and API are on the same domain.

Advanced: API on Different Domain

If your API server is on a different hostname than where the UI is served (uncommon):

Rebuild the Docker image with build arguments:

docker build \
  --build-arg PUBLIC_SERVER_HOSTNAME=api.example.com \
  --build-arg PUBLIC_SERVER_PORT=8080 \
  -f backend/Dockerfile \
  -t scanopy-server:custom \
  .

Then use your custom image in docker-compose:

scanopy-server:
  image: scanopy-server:custom
  # ... rest of config

Session Security

Secure Cookies

Important: Enable secure cookies when running Scanopy behind HTTPS.

environment:
  - SCANOPY_USE_SECURE_SESSION_COOKIES=true

When to enable:

Behind a reverse proxy with TLS (Nginx, Traefik, Caddy)
Using a domain with HTTPS
Production deployments

When to disable (default):

Internal networks without HTTPS
Development environments
Accessing via IP address without TLS

Effect:

true: Cookies marked as Secure, only sent over HTTPS
false: Cookies sent over HTTP and HTTPS

Environment Files

For easier management, use .env files:

Create .env:

# Database
SCANOPY_DATABASE_URL=postgresql://postgres:password@db:5432/scanopy

# Server
SCANOPY_SERVER_PORT=60072
SCANOPY_SERVER_PUBLIC_URL=http://your-domain.com:60072
SCANOPY_LOG_LEVEL=info
SCANOPY_USE_SECURE_SESSION_COOKIES=false

# SMTP (optional - for password reset and notifications)
SCANOPY_SMTP_RELAY=smtp.gmail.com
SCANOPY_SMTP_USERNAME=[email protected]
SCANOPY_SMTP_PASSWORD=your-app-password
SCANOPY_SMTP_EMAIL=[email protected]

# Daemon
SCANOPY_INTEGRATED_DAEMON_URL=http://172.17.0.1:60073

# Metrics (optional - for Prometheus scraping)
SCANOPY_METRICS_TOKEN=your-secure-metrics-token
SCANOPY_EXTERNAL_SERVICE_PROMETHEUS_ALLOWED_IPS=192.168.1.0/24

Reference in docker-compose.yml:

services:
  scanopy-server:
    image: ghcr.io/scanopy/scanopy/server:latest
    env_file:
      - .env
    # ... rest of config

On this page