Self-Hosting
Setup Guide
Install and configure VulnRadar locally or in production. Three deployment paths: local Node, Docker, or a generic Node host.
Prerequisites
Before you begin, ensure you have the following installed:
Node.js 22 LTS
JavaScript runtime. package.json pins engines.node to >=22.0.0 <23.0.0 and .npmrc makes that range a hard install failure, the Dockerfile builds on node:22.11.0-alpine, and CI runs on Node 22 only. See the Node Version Policy on the Developers page.. Download from nodejs.org
node --version # Check versionnpm 10+
Package manager. Use npm, not pnpm or yarn: this repo's node_modules layout and lockfile assume npm..
npm --version # Check versionPostgreSQL 14+
Database server. Single Postgres instance handles app, sessions, and rate-limit tables.. Download from www.postgresql.org/download
psql --version # Check versionInstallation Steps
Step 1: Clone the Repository
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.devStep 2: Install Dependencies
npm ci.npmrc sets engine-strict=true, so an install under a Node outside engines (>=22.0.0 <23.0.0) fails instead of warning. It holds no install-script allow-list: npm has no such mechanism, and the Docker build installs with --ignore-scripts because nothing in the production tree needs one (sharp and the Next SWC binaries ship prebuilt as optional dependencies).
Database Setup
Configure PostgreSQL for VulnRadar.
Option A: Dedicated database (no Docker)
psql -U postgres
CREATE DATABASE vulnradar;
CREATE USER vulnradar_user WITH PASSWORD 'strong_password_here';
GRANT ALL PRIVILEGES ON DATABASE vulnradar TO vulnradar_user;
\qOption B: Docker Compose (recommended)
The included docker-compose.yml provisions Postgres as user vulnradar and database vulnradar by default. POSTGRES_PASSWORD has no default: compose refuses to start until you set it in .env. The database port is not published to the host at all, so it is reachable only from inside the compose network, at postgres:5432. See the Docker section below.
Schema auto-creates on boot
instrumentation.ts runs CREATE TABLE IF NOT EXISTS for every table on first server boot. No manual migration is required for a fresh database. For databases upgraded from an older schema, see Schema Migration.
Environment Configuration
Secrets and per-deployment overrides go in .env (or .env.local for local-only overrides; Next.js loads .env.local with higher precedence than .env).
Create .env from the template
cp .env.example .envOpen .env and fill in at minimum:
# Database
DATABASE_URL=postgresql://vulnradar:your-password@localhost:5432/vulnradar
DATABASE_SSL=false
# Public URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
# API key encryption (REQUIRED). Generate with:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
API_KEY_ENCRYPTION_KEY=your-64-character-hex-keyOptional: SMTP, Stripe, Discord, Turnstile. Full reference on the Configuration page.
App Configuration
Non-secret deployment tunables live in lib/config/config-values.ts. Branding, app name, and SEO values are baked in at build time, so edit those before the first build and restart to pick up changes. Most of the rest (rate limits, feature flags, billing, scan timeouts) can also be changed at runtime after signup, from /admin’s Settings tab, with no restart. See Configuration for which is which.
Common changes
CONFIG_APP_NAME,CONFIG_APP_URL,CONFIG_APP_DESCRIPTION: brandingCONFIG_SUPPORT_EMAIL,CONFIG_LEGAL_EMAIL,CONFIG_SECURITY_EMAIL: outbound email addressesCONFIG_BILLING_ENABLED = false: disable Stripe entirelyCONFIG_FEATURE_DEMO_MODE = false: hide the/demopage
Full reference: /docs/config.
Running the Application
Production
npm run build
npm startListens on port 3000 by default. Put behind a reverse proxy (Caddy, Traefik, nginx) for TLS.
Verification
1. Access the app
Open http://localhost:3000. The landing page renders and middleware redirects unauthenticated users to /landing.
2. Sign up the first user
Visit /signup. Email verification is required before login if SMTP is configured.
3. Promote to admin
The first account on a fresh instance is already super_admin, so there is nothing to run. The command below promotes a later account to admin, which is one level lower. Running it against the first account demotes it, and nothing in the product can restore super_admin.
docker compose exec postgres psql -U vulnradar -d vulnradar -c \
"UPDATE users SET role = 'admin' WHERE email = '[email protected]'"4. Generate an API key
Open /profile → API Keys → Generate New Key. The raw key is shown once; copy it immediately.
5. Run a scan
curl -X POST "https://vulnradar.dev/api/v3/scan" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Troubleshooting
Database connection refused
Error: ECONNREFUSED 127.0.0.1:5432
# Local install
sudo systemctl status postgresql
sudo systemctl start postgresql
# Docker
docker compose ps postgres
docker compose logs postgresPort 3000 already in use
Error: EADDRINUSE: address already in use :::3000
# Find the process
lsof -i :3000
# Or use a different port (Next.js CLI flag)
npm run dev -- -p 3001Module not found after fresh clone
Error: Cannot find module 'next'
# Remove stale lockfile + reinstall
rm -rf node_modules .next
npm ciSchema version mismatch at startup
Error: SCHEMA VERSION MISMATCH ... Database schema: v2.0.0 / App requires: v3.0.0
# Run the migration tool (interactive)
npm run db:migrate
# Or, in dry-run first
npm run db:migrate:dry-runValidation: API_KEY_ENCRYPTION_KEY invalid
Error: API_KEY_ENCRYPTION_KEY must be a 64-character hex string (32 bytes).
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Paste the output into .env, restart.Deployment Options
Vercel
VulnRadar is a standard Next.js 15 App Router app and runs on Vercel out of the box. Use Neon or any other serverless Postgres for the database. Configure environment variables in the Vercel dashboard before deploying.
- Push the repo to GitHub.
- Import the project in Vercel.
- Add the required env vars (see above).
- Deploy.
Self-hosted (Linux)
- Provision a server with Node 22 LTS and PostgreSQL 14+.
- Clone the repo, install dependencies (
npm ci). - Configure
.env. npm run build && npm start- Manage the process with PM2 or systemd. Reverse-proxy (Caddy, Traefik, nginx) for TLS.
Docker Compose
See the Docker section below.
Docker Deployment
Deploy VulnRadar with the included docker-compose.yml. Two services, Postgres and the app, each with its own healthcheck; the app waits for Postgres to report healthy before it starts.
Step 1: Project directory
mkdir -p ~/vulnradar
cd ~/vulnradarStep 2: Get docker-compose.yml
Either pull the prebuilt image from GHCR:
curl -O https://raw.githubusercontent.com/VulnRadar/vulnradar.dev/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/VulnRadar/vulnradar.dev/main/.env.exampleOr build from source locally:
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.dev
cp .env.example .envStep 3: Configure .env
# Required
DATABASE_URL=postgresql://vulnradar:your-strong-password@postgres:5432/vulnradar
NEXT_PUBLIC_APP_URL=https://yourdomain.com
API_KEY_ENCRYPTION_KEY=your-64-character-hex-key
# Used by docker-compose.yml to provision Postgres
POSTGRES_DB=vulnradar
POSTGRES_USER=vulnradar
POSTGRES_PASSWORD=your-strong-password
# Host port the app is published on, and the interface it binds to.
# HOST_BIND defaults to 127.0.0.1 because the compose file assumes a
# reverse proxy on the same host; set 0.0.0.0 to publish on every
# interface. Postgres is not published to the host at all.
APP_PORT=3000
# HOST_BIND=0.0.0.0Step 4: Start
docker compose up -ddocker compose psStep 5: Verify
docker compose logs -f appLook for the startup banner and Database schema verified successfully.
Common operations
Tail logs
docker compose logs -f appStop (keep data)
docker compose downFull reset (drop volumes)
docker compose down -vUpdate
docker compose pull && docker compose up -dRestart only the app
docker compose restart appOpen a psql shell
docker compose exec postgres psql -U vulnradar -d vulnradarSchema Migration
When upgrading between schema versions (e.g. v1 → v2), use the interactive migration tool. The migrator reads vulnradar_schema_meta to detect the current schema, picks the target version, builds a DDL plan, and applies it in a single transaction.
Run a migration
# Preview the plan first
npm run db:migrate:dry-run
# Then run for real (interactive)
npm run db:migrateFlags accepted by the CLI: --dry-run, --yes (non-interactive, accept every default) and --help. It also goes non-interactive on its own whenever stdin is not a terminal, which is what makes docker compose run --rm app npm run db:migrate work in a pipeline. The target version is selected interactively; downgrades require typing yes-delete-data.
Side-by-side clone
To create a new database (e.g. for testing an upgrade on a copy of production), use db:create:
# Preview
npm run db:create:dry-run
# Interactive: choose source DB, target DB name, copy data?
npm run db:createVersion Check
VulnRadar compares its installed version against the latest GitHub release once per hour.
Programmatic check
curl https://vulnradar.dev/api/versionUnauthenticated. Cached for 1 hour upstream of GitHub.
{
"current": "3.9.1",
"engine": "3.3.2",
"latest": "3.9.1",
"status": "up-to-date",
"message": "You're running the latest version.",
"release_url": "https://github.com/VulnRadar/vulnradar.dev/releases/tag/v3.9.1"
}Status values
up-to-date: running the latest releasebehind: a newer release exists;release_urlpoints to itahead: running a version newer than the latest release (development / RC)unknown: GitHub unreachable, rate-limited, or the repo does not exist