Self-Hosting

Overview

Shieldome can be deployed on any Linux server you control - a VPS, a bare-metal machine, or a private cloud instance. The on-premise edition runs the same engine as the hosted service, but all data stays on your infrastructure. A license key is required for production use; contact [email protected] to obtain one.

Requirements

• Docker 24+ and Docker Compose v2+ (docker compose command)
• A server with at least 2 GB RAM and 10 GB free disk space
• A domain name pointed at your server's IP (required for HTTPS and OOB detection)
• Ports 80 and 443 open in your firewall (for the reverse proxy)
• An on-premise license key - contact [email protected]

Quick start

1. Get the files

Clone the repository or download the release archive:

git clone https://github.com/shieldome/scanner.git
cd scanner

# Or pull the pre-built image without the source:
mkdir shieldome-onprem && cd shieldome-onprem
curl -O https://raw.githubusercontent.com/shieldome/scanner/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/shieldome/scanner/main/.env.example

2. Configure environment

cp .env.example .env
# Open .env in your editor and fill in the required values
nano .env

At minimum, set these five values before starting:

• SHIELDOME_SECRET_KEY - generate a strong random key (see below)
• POSTGRES_PASSWORD - set a strong database password
• DATABASE_URL - uncomment and update with your Postgres password
• APP_BASE_URL - your public domain, e.g. https://scan.example.com
• LICENSE_KEY - your on-premise license key

# Generate a secure secret key
python -c "import secrets; print(secrets.token_hex(32))"

3. Start the stack

docker compose up -d

This starts PostgreSQL, Redis, the Shieldome app, and the Celery background workers. First boot may take 30-60 seconds as images are pulled and the database is initialised. Check that all services are running:

docker compose ps
docker compose logs -f shieldome

Once healthy, the app is reachable on port 5000. You should place it behind a reverse proxy (see SSL/HTTPS setup below) before exposing it to the internet.

Environment variables

See .env.example in the repository for the complete list including email, webhook, payment, and scanner tuning variables.

SSL/HTTPS setup

Run Shieldome behind a reverse proxy that handles TLS termination. Two common options:

Option A - Caddy (recommended, auto-HTTPS)

Caddy automatically obtains and renews Let's Encrypt certificates.

scan.example.com {
    reverse_proxy localhost:5000
}

# Install Caddy (Debian/Ubuntu)
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

# Place your Caddyfile at /etc/caddy/Caddyfile, then:
sudo systemctl reload caddy

Option B - nginx + Certbot

server {
    listen 80;
    server_name scan.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name scan.example.com;

    ssl_certificate     /etc/letsencrypt/live/scan.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/scan.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    location / {
        proxy_pass         http://127.0.0.1:5000;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;

        # Required for Server-Sent Events (live scan progress)
        proxy_buffering    off;
        proxy_read_timeout 300s;
    }
}

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d scan.example.com

Updating

To pull the latest Shieldome image and restart with zero downtime:

docker compose pull
docker compose up -d

Docker Compose will restart only the services whose images have changed. Database migrations run automatically on startup.

Backups

Back up the PostgreSQL database regularly. A simple daily dump:

# Create a timestamped dump
docker compose exec postgres pg_dump -U shieldome shieldome \
  > backup-$(date +%Y%m%d-%H%M%S).sql

# Restore from a dump
docker compose exec -T postgres psql -U shieldome shieldome \
  < backup-20260101-120000.sql

Also back up the shieldome-reports Docker volume (or the ./reports directory if you use a bind mount) to preserve generated PDF reports.

OOB detection setup

Out-of-band (OOB) detection finds vulnerabilities - like blind SSRF and blind SQLi - that produce no visible response. Shieldome sends probes with unique DNS hostnames; if the target resolves them, a callback hits your OOB listener and the finding is confirmed.

To enable OOB detection on your self-hosted instance:

1. Create a DNS A record pointing a wildcard subdomain at your server IP:
   DNSCopy

   *.oob.scan.example.com  A  203.0.113.10   (your server IP)

2. Set OOB_DNS_DOMAIN=oob.scan.example.com in your .env.
3. Set INTERNAL_SECRET to a strong random value (used to authenticate callbacks).
4. Restart the stack: docker compose up -d

Shieldome's built-in DNS listener starts automatically when OOB_DNS_DOMAIN is configured. No additional software is required.

License key

On-premise deployments require a license key set as LICENSE_KEY in your .env. The app will start without a key in evaluation mode (limited scans per day); production use requires a valid license.

To obtain a license key, contact [email protected] with your company name and expected scan volume. Licenses are per-installation and tied to your APP_BASE_URL.