Skip to content

Installation

Jump to bottom
homelabforge edited this page Feb 8, 2026 · 3 revisions

Installation

Comprehensive installation guide for VulnForge across different environments.

Table of Contents

Docker Compose (Recommended)

Full Stack with Socket Proxy

Recommended for production use - Uses Docker socket proxy for security.

version: "3.8"

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: socket-proxy-ro
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      INFO: 1
      NETWORKS: 1
      VOLUMES: 1
    networks:
      - vulnforge
    restart: unless-stopped

  trivy:
    image: aquasec/trivy:latest
    container_name: trivy
    command: server --listen 0.0.0.0:8080
    volumes:
      - trivy-cache:/root/.cache
    networks:
      - vulnforge
    restart: unless-stopped

  vulnforge:
    image: ghcr.io/homelabforge/vulnforge:latest
    container_name: vulnforge
    ports:
      - "8787:8787"
    volumes:
      - vulnforge-data:/data
      # Host mounts for native compliance checker
      - /etc/docker:/host/etc/docker:ro
      - /etc/audit:/host/etc/audit:ro
    environment:
      # Docker connection
      DOCKER_SOCKET_PROXY: tcp://socket-proxy-ro:2375
      TRIVY_CONTAINER_NAME: trivy
      HOST_ETC_PATH: /host/etc

      # Scanning
      SCAN_SCHEDULE: "0 2 * * *"  # Daily at 2 AM
      SCAN_TIMEOUT: 300
      PARALLEL_SCANS: 3

      # Database
      DATABASE_URL: sqlite+aiosqlite:////data/vulnforge.db

      # Timezone (optional)
      TZ: America/New_York
    networks:
      - vulnforge
    depends_on:
      - socket-proxy
      - trivy
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8787/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  trivy-cache:
    name: vulnforge-trivy-cache
  vulnforge-data:
    name: vulnforge-data

networks:
  vulnforge:
    name: vulnforge

Bare Metal Installation

Prerequisites

  • Python 3.14+
  • Bun 1.3.4+ (for development)
  • Docker access
  • 1GB RAM minimum

Installation Steps

1. Clone Repository

git clone https://github.com/homelabforge/vulnforge.git
cd vulnforge

2. Install Backend Dependencies

cd backend
python3.14 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

3. Install Frontend Dependencies

cd ../frontend
bun install

4. Build Frontend

bun run build

5. Configure Environment

Create .env file in backend/:

# Database
DATABASE_URL=sqlite+aiosqlite:///./data/vulnforge.db

# Docker (direct socket - use socket proxy in production)
DOCKER_HOST=unix:///var/run/docker.sock
TRIVY_CONTAINER_NAME=trivy

# Scanning
SCAN_SCHEDULE=0 2 * * *
SCAN_TIMEOUT=300
PARALLEL_SCANS=3

# Server
PORT=8787
LOG_LEVEL=INFO

6. Initialize Database

cd backend
mkdir -p data
python -c "from app.db import init_db; import asyncio; asyncio.run(init_db())"

7. Start Trivy Server

docker run -d --name trivy \
  -p 8080:8080 \
  -v trivy-cache:/root/.cache \
  aquasec/trivy:latest \
  server --listen 0.0.0.0:8080

8. Run Backend

cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8787

Or with Granian (production):

granian --interface asgi --host 0.0.0.0 --port 8787 --workers 1 app.main:app

NAS Deployment

Synology NAS

Via Container Manager

  1. Open Container Manager
  2. Go to Project tab
  3. Create new project named vulnforge
  4. Paste the Docker Compose YAML from above
  5. Click Build and Start

Volume Mappings

  • Container: /data → Host: /volume1/docker/vulnforge/data
  • Container: /root/.cache (Trivy) → Host: /volume1/docker/vulnforge/trivy-cache

QNAP NAS

Via Container Station

  1. Open Container Station
  2. Go to Create → Create Application
  3. Paste Docker Compose YAML
  4. Adjust volume paths to QNAP format:
    • /share/Container/vulnforge/data
    • /share/Container/vulnforge/trivy-cache

TrueNAS Scale

  1. Navigate to Apps
  2. Click Discover Apps → Custom App
  3. Use Docker Compose YAML
  4. Configure storage:
    • Host Path: /mnt/pool/apps/vulnforge/data
    • Mount Path: /data

Reverse Proxy Setup

Traefik

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.vulnforge.rule=Host(`vulnforge.yourdomain.com`)"
  - "traefik.http.routers.vulnforge.entrypoints=websecure"
  - "traefik.http.routers.vulnforge.tls.certresolver=letsencrypt"
  - "traefik.http.services.vulnforge.loadbalancer.server.port=8787"

Nginx Proxy Manager

  1. Add Proxy Host
  2. Domain Names: vulnforge.yourdomain.com
  3. Forward Hostname/IP: vulnforge (container name) or 192.168.1.x (host IP)
  4. Forward Port: 8787
  5. SSL tab: Request SSL certificate

Caddy

vulnforge.yourdomain.com {
    reverse_proxy vulnforge:8787
}

nginx (Manual)

server {
    listen 443 ssl http2;
    server_name vulnforge.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/vulnforge.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vulnforge.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://vulnforge:8787;
        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;

        # SSE support for real-time scan progress
        proxy_buffering off;
        proxy_cache off;
        proxy_set_header Connection '';
        proxy_http_version 1.1;
        chunked_transfer_encoding off;
    }
}

Environment Variables

Variable Default Description
PORT 8787 HTTP port for web interface
DATABASE_URL sqlite+aiosqlite:////data/vulnforge.db SQLite database path
DOCKER_SOCKET_PROXY tcp://socket-proxy-ro:2375 Docker socket proxy URL
DOCKER_HOST None Direct Docker socket (not recommended for production)
TRIVY_CONTAINER_NAME trivy Trivy container name
TRIVY_SERVER None Trivy server URL (e.g., http://trivy:8080)
HOST_ETC_PATH /host/etc Host /etc mount path for compliance checks
SCAN_SCHEDULE 0 2 * * * Cron schedule for automatic scans
SCAN_TIMEOUT 300 Scan timeout in seconds
PARALLEL_SCANS 3 Number of concurrent scans
LOG_LEVEL INFO Logging level (DEBUG, INFO, WARNING, ERROR)
TZ UTC Timezone for scheduling

See Environment Variables for complete reference.

Post-Installation

After installation:

  1. First-Time Setup - Initial configuration
  2. Authentication - Secure your instance
  3. Notifications - Configure alerts
  4. Scan Settings - Customize scanning behavior

Upgrading

See Upgrading for version migration guides.

Troubleshooting

Having issues? Check Troubleshooting for solutions.

Clone this wiki locally