Skip to content

Upgrading

Jump to bottom
homelabforge edited this page Apr 5, 2026 · 4 revisions

Upgrading VulnForge

Version migration guides and breaking changes.

Table of Contents

General Upgrade Process

Docker Compose

# 1. Backup database
docker cp vulnforge:/data/vulnforge.db ./vulnforge.db.backup

# 2. Pull latest image
docker compose pull vulnforge

# 3. Stop and recreate container
docker compose up -d vulnforge

# 4. Verify upgrade
docker logs vulnforge | head -20

Check Version

# View current version
docker inspect vulnforge | grep -i "version"

# Or check in UI footer
# Dashboard → Bottom right corner shows version

Post-Upgrade Session Invalidation

After upgrading, all existing JWT sessions are invalidated. Users will need to re-login once. API keys are not affected.

This is automatic and requires no action — users simply log in again.

Version 3.3.0

Release Date: December 16, 2025

What's New

Major Changes:

  • 🚀 Migrated to Bun 1.3.4 - 2-5x faster frontend builds
  • ⚡ Updated to Vite 7.3.0 - Improved build performance
  • 🎨 React 19 & TypeScript improvements
  • 🧪 Vitest 3.1 for testing - More mature testing framework
  • 🐍 pytest 9.0.2 & pytest-asyncio 1.3.0 - Backend test improvements

Dependency Updates:

  • recharts 3.6.0 (charts)
  • zod 4.2.1 (validation)
  • TailwindCSS 4.1.18 (styling)
  • typescript-eslint 8.50.0 (linting)

Breaking Changes

None - fully backward compatible with 3.x configurations.

Migration Steps

No special migration required. Follow General Upgrade Process.

Version 3.0.0

Release Date: (Historical - example version)

What's New

Major Changes:

  • 🔐 User Authentication System - Local login and OIDC/SSO support
  • 🔑 API Key Management - Simple, secure API keys for external tools
  • 🔔 ntfy Notifications - Smart alerting with configurable thresholds
  • 📊 KEV Tracking - CISA Known Exploited Vulnerabilities
  • ✅ Compliance Monitoring - Native VulnForge Checker and Dive integration
  • 🔐 Secret Scanning - Detect exposed credentials
  • 📡 Real-time Progress - Server-Sent Events (SSE)

Breaking Changes

1. Authentication system simplified (v4.0+)

If upgrading from v3.x, the API authentication system has been completely refactored:

Removed:

  • Authentik ForwardAuth provider
  • Custom Headers provider
  • Basic Auth provider
  • Complex multi-provider configuration

Added:

  • Simple API key management UI
  • Database-backed keys with SHA256 hashing
  • One-click create/revoke operations

Action Required:

  1. All old API keys are invalidated
  2. Create new API keys via Settings → Security → API Keys
  3. Update external tools (TideWatch, scripts) with new keys
  4. Old auth_enabled and auth_provider settings disabled automatically by migration

2. Database schema changes

New tables added:

  • auth_settings
  • compliance_scans
  • secrets

Action: Database migrates automatically on first startup.

3. Environment variable changes

Old Variable New Variable Notes
TRIVY_URL TRIVY_SERVER Both supported for compatibility
NOTIFY_URL NTFY_URL Renamed for clarity

Action: Update docker-compose.yml if using old variable names.

Migration Steps

# 1. Backup database
docker cp vulnforge:/data/vulnforge.db ./vulnforge-2.x-backup.db

# 2. Stop VulnForge
docker compose down vulnforge

# 3. Pull v3.0.0
docker compose pull vulnforge

# 4. Start VulnForge (database auto-migrates)
docker compose up -d vulnforge

# 5. Monitor logs for migration
docker logs -f vulnforge

# Look for: "Database migration complete"

# 6. Configure authentication (optional but recommended)
# Open UI → Settings → Authentication

Backup and Restore

Backup

Automatic Backups

VulnForge uses SQLite WAL mode with automatic checkpointing.

Recommended: Set up cron job for daily backups:

#!/bin/bash
# /etc/cron.daily/vulnforge-backup

BACKUP_DIR="/backups/vulnforge"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Backup database
docker cp vulnforge:/data/vulnforge.db "$BACKUP_DIR/vulnforge-$DATE.db"

# Keep only last 30 days
find "$BACKUP_DIR" -name "vulnforge-*.db" -mtime +30 -delete

# Optional: compress old backups
find "$BACKUP_DIR" -name "vulnforge-*.db" -mtime +7 ! -name "*.gz" -exec gzip {} \;

Make executable:

chmod +x /etc/cron.daily/vulnforge-backup

Manual Backup

# Copy database file
docker cp vulnforge:/data/vulnforge.db ./vulnforge-backup-$(date +%Y%m%d).db

# Or use docker volume backup
docker run --rm \
  -v vulnforge-data:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/vulnforge-data-$(date +%Y%m%d).tar.gz /data

Restore

From Database File

# Stop VulnForge
docker compose stop vulnforge

# Restore database
docker cp ./vulnforge-backup.db vulnforge:/data/vulnforge.db

# Start VulnForge
docker compose start vulnforge

From Volume Backup

# Stop VulnForge
docker compose down vulnforge

# Delete old volume (DANGER!)
docker volume rm vulnforge-data

# Create new volume
docker volume create vulnforge-data

# Restore data
docker run --rm \
  -v vulnforge-data:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/vulnforge-data-20251216.tar.gz -C /

# Start VulnForge
docker compose up -d vulnforge

Rollback

Rollback to Previous Version

If upgrade fails or causes issues:

# 1. Stop VulnForge
docker compose stop vulnforge

# 2. Restore database backup
docker cp ./vulnforge-2.x-backup.db vulnforge:/data/vulnforge.db

# 3. Pin to specific version in docker-compose.yml
services:
  vulnforge:
    image: ghcr.io/homelabforge/vulnforge:2.7.0  # Specific version

# 4. Restart
docker compose up -d vulnforge

Version Pinning

Recommended for production:

# docker-compose.yml
services:
  vulnforge:
    image: ghcr.io/homelabforge/vulnforge:3.3.0  # Pin to specific version

Advantages:

  • Prevents unexpected changes
  • Controlled upgrade process
  • Easy rollback

Disadvantages:

  • Miss security patches
  • Manual version updates required

Best practice: Pin major.minor version, allow patch updates:

image: ghcr.io/homelabforge/vulnforge:3.3  # Gets 3.3.x patches

Upgrade Checklist

Before upgrading:

  • ✅ Read release notes for breaking changes
  • ✅ Backup database
  • ✅ Test upgrade in development environment first
  • ✅ Schedule during low-usage window
  • ✅ Monitor logs after upgrade
  • ✅ Verify core functionality (scan, triage, notifications)
  • ✅ Keep backup for 30 days minimum

After upgrading:

  • ✅ Check version in UI footer
  • ✅ Run test scan
  • ✅ Send test notification
  • ✅ Review Settings for new options
  • ✅ Update documentation if using custom integrations

Troubleshooting Upgrades

Database migration fails

Symptom: VulnForge fails to start after upgrade, logs show "Migration failed"

Recovery:

# Restore backup
docker cp ./vulnforge-backup.db vulnforge:/data/vulnforge.db

# Try manual migration (if available)
docker exec vulnforge python /app/backend/migrate.py

# If fails, rollback to previous version

Settings lost after upgrade

Cause: Database restore from old version

Solution: Reconfigure settings via UI (Settings page)

Settings are stored in database, not environment variables.

Scan format incompatible

Cause: Major version upgrade changed scan result schema

Solution: Re-run scans after upgrade. Old scan results may not display correctly.

Stay Updated

Next Steps

Clone this wiki locally