Skip to main content

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

bash
node --version  # Check version

npm 10+

Package manager. Use npm, not pnpm or yarn: this repo's node_modules layout and lockfile assume npm..

bash
npm --version  # Check version

PostgreSQL 14+

Database server. Single Postgres instance handles app, sessions, and rate-limit tables.. Download from www.postgresql.org/download

bash
psql --version  # Check version

Git 2.0+

Version control.. Download from git-scm.com

bash
git --version  # Check version

Installation Steps

Step 1: Clone the Repository

bash
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.dev

Step 2: Install Dependencies

bash
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)

SQL
psql -U postgres

CREATE DATABASE vulnradar;
CREATE USER vulnradar_user WITH PASSWORD 'strong_password_here';
GRANT ALL PRIVILEGES ON DATABASE vulnradar TO vulnradar_user;
\q

Option 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

bash
cp .env.example .env

Open .env and fill in at minimum:

bash
# 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-key

Optional: 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: branding
  • CONFIG_SUPPORT_EMAIL, CONFIG_LEGAL_EMAIL, CONFIG_SECURITY_EMAIL: outbound email addresses
  • CONFIG_BILLING_ENABLED = false: disable Stripe entirely
  • CONFIG_FEATURE_DEMO_MODE = false: hide the /demo page

Full reference: /docs/config.

Running the Application

Development (with hot reload)

bash
npm run dev

Available at http://localhost:3000

Production

bash
npm run build
npm start

Listens 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.

bash
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

bash
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

bash
# Local install
sudo systemctl status postgresql
sudo systemctl start postgresql

# Docker
docker compose ps postgres
docker compose logs postgres

Port 3000 already in use

Error: EADDRINUSE: address already in use :::3000

bash
# Find the process
lsof -i :3000

# Or use a different port (Next.js CLI flag)
npm run dev -- -p 3001

Module not found after fresh clone

Error: Cannot find module 'next'

bash
# Remove stale lockfile + reinstall
rm -rf node_modules .next
npm ci

Schema version mismatch at startup

Error: SCHEMA VERSION MISMATCH ... Database schema: v2.0.0 / App requires: v3.0.0

bash
# Run the migration tool (interactive)
npm run db:migrate

# Or, in dry-run first
npm run db:migrate:dry-run

Validation: API_KEY_ENCRYPTION_KEY invalid

Error: API_KEY_ENCRYPTION_KEY must be a 64-character hex string (32 bytes).

bash
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.

  1. Push the repo to GitHub.
  2. Import the project in Vercel.
  3. Add the required env vars (see above).
  4. Deploy.

Self-hosted (Linux)

  1. Provision a server with Node 22 LTS and PostgreSQL 14+.
  2. Clone the repo, install dependencies (npm ci).
  3. Configure .env.
  4. npm run build && npm start
  5. 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

bash
mkdir -p ~/vulnradar
cd ~/vulnradar

Step 2: Get docker-compose.yml

Either pull the prebuilt image from GHCR:

bash
curl -O https://raw.githubusercontent.com/VulnRadar/vulnradar.dev/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/VulnRadar/vulnradar.dev/main/.env.example

Or build from source locally:

bash
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.dev
cp .env.example .env

Step 3: Configure .env

bash
# 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.0

Step 4: Start

bash
docker compose up -d
bash
docker compose ps

Step 5: Verify

bash
docker compose logs -f app

Look for the startup banner and Database schema verified successfully.

Common operations

Tail logs

bash
docker compose logs -f app

Stop (keep data)

bash
docker compose down

Full reset (drop volumes)

bash
docker compose down -v

Update

bash
docker compose pull && docker compose up -d

Restart only the app

bash
docker compose restart app

Open a psql shell

bash
docker compose exec postgres psql -U vulnradar -d vulnradar

Schema 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

bash
# Preview the plan first
npm run db:migrate:dry-run

# Then run for real (interactive)
npm run db:migrate

Flags 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:

bash
# Preview
npm run db:create:dry-run

# Interactive: choose source DB, target DB name, copy data?
npm run db:create

Version Check

VulnRadar compares its installed version against the latest GitHub release once per hour.

Programmatic check

bash
curl https://vulnradar.dev/api/version

Unauthenticated. Cached for 1 hour upstream of GitHub.

JSON
{
  "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 release
  • behind: a newer release exists; release_url points to it
  • ahead: running a version newer than the latest release (development / RC)
  • unknown: GitHub unreachable, rate-limited, or the repo does not exist
Setup Guide: Install and First Scan | VulnRadar