On-Premise Installation

This guide covers the installation of Vulnotes for on-premise deployments using the Vulnotes CLI.

System Requirements

Minimum Requirements

• CPU: 2 cores
• RAM: 4GB
• Storage: 20GB

Recommended Requirements

• CPU: 4+ cores
• RAM: 8GB+
• Storage: 50GB+

Software Dependencies

• Docker and Docker Compose
• curl, jq, OpenSSL, and a SHA-256 utility

Install Dependencies

Docker

Follow the official Docker installation guide for your OS: docs.docker.com/engine/install

Other Dependencies

# Ubuntu/Debian
sudo apt-get install -y curl jq openssl coreutils

Install the Vulnotes CLI

Install Script

curl -fsSLO https://raw.githubusercontent.com/vulnotes/vulnotes-cli/master/install.sh
bash install.sh

The installer downloads the latest published CLI release and verifies its SHA-256 checksum before installing it.

Manual Install

git clone https://github.com/vulnotes/vulnotes-cli.git
cd vulnotes-cli
chmod +x vulnotes

When using the manual install, replace vulnotes with ./vulnotes in the commands below.

Get a Provisioning Token

1. Go to manager.vulnotes.com
2. Log in with your on-premise license
3. Generate a provisioning token

WARNING

Provisioning tokens expire after 30 minutes.

Initialize Vulnotes

Create a directory for the deployment, then run the initialization command from that directory:

mkdir -p ~/vulnotes
cd ~/vulnotes
vulnotes init --token YOUR_PROVISIONING_TOKEN

The current directory is used by default. To use another location, pass it with --dir:

vulnotes init --token YOUR_PROVISIONING_TOKEN --dir /path/to/vulnotes

The CLI will interactively ask you to configure:

• Domain/URL: e.g. https://vulnotes.company.com or http://localhost
• HTTP port: default 80
• Network binding: 127.0.0.1 (local only) or 0.0.0.0 (network accessible)

The init command handles everything automatically:

• Authenticates with the Vulnotes private Docker registry
• Generates all configuration files (.env, docker-compose.yml, nginx.conf, license.json)
• Creates the backup directory
• Enables automatic daily backups at 2:00 AM

Start Vulnotes

vulnotes start

This pulls the latest Docker images and starts all services. Once started, access Vulnotes.

SSL / HTTPS

The CLI configures Vulnotes with HTTP by default. For production deployments, place a reverse proxy in front of Vulnotes with SSL termination.

You can use Traefik, Caddy, or an Nginx reverse proxy with Let's Encrypt certificates. Vulnotes supports the X-Forwarded-Proto header for proper SSL detection behind a proxy.

WARNING

Running without HTTPS in production is not recommended. All authentication tokens and session data would be transmitted in plaintext.

CLI Commands

Lifecycle

Command	Description
vulnotes start	Pull latest images and start all services
vulnotes stop	Stop all services
vulnotes restart	Restart all services
vulnotes update	Refresh managed configuration, pull the latest images, and recreate containers

Logs

# View all logs
vulnotes logs

# View logs for a specific service
vulnotes logs backend

# Follow logs in real-time
vulnotes logs -f

# Show last 50 lines
vulnotes logs -n 50

Available services: nginx, backend, frontend, mongodb, puppeteer, mcp

Backup & Restore

# Create a backup
vulnotes backup

This creates a timestamped archive in the backups/ directory containing the MongoDB database, uploaded files, .env, and Nginx configuration.

# Restore the database and uploaded files
vulnotes restore /path/to/backup.tar.gz

# Also restore .env and nginx.conf
vulnotes restore /path/to/backup.tar.gz --restore-config

Restore keeps the current .env and nginx.conf by default. Use --restore-config only with an archive you created and trust, since it replaces the current secrets and Nginx configuration.

INFO

Before restoring, the CLI asks whether it should create a safety backup of the current instance.

Automatic Backups

Automatic backups are enabled during initialization and run every day at 2:00 AM. The retention policy keeps daily backups for 7 days, one backup per week for 4 weeks, and one backup per month for 6 months.

# Check the current schedule
vulnotes backup-schedule status

# Enable or disable automatic backups
vulnotes backup-schedule enable
vulnotes backup-schedule disable

# Apply the retention policy manually
vulnotes backup-rotate

Reset an Instance

vulnotes reset

Reset removes the database, uploaded files, logs, and license cache, then starts a clean instance. It keeps .env, license.json, nginx.conf, and docker-compose.yml.

The CLI creates a backup before deleting any data and requires two confirmations. Vulnotes must be running so this backup can be created.

Help

vulnotes help
vulnotes version

The CLI checks for new releases automatically. Set VULNOTES_SKIP_UPDATE_CHECK=1 if update checks must be disabled for a command.

Architecture

The deployment consists of 6 Docker containers:

Service	Description
nginx	Reverse proxy, rate limiting, security headers
backend	Node.js API server with Socket.IO
frontend	Next.js application
mongodb	Database
puppeteer	Headless Chrome for PDF generation
mcp	Model Context Protocol server for AI integrations

All containers run on an isolated Docker bridge network. Data is persisted using Docker named volumes.

Troubleshooting

Port already in use

If port 80 is taken by another service, you can reinitialize with a different port or edit the generated docker-compose.yml to change the port mapping.

Cannot connect to Docker daemon

Make sure Docker is running and your user is in the docker group:

sudo systemctl start docker
sudo usermod -aG docker $USER

Log out and back in after adding yourself to the group.

Containers not starting

Check the logs to identify the failing service:

vulnotes logs
vulnotes logs backend
vulnotes logs mongodb

Common causes:

• Insufficient disk space for Docker volumes
• MongoDB needs a few seconds to become healthy on first start
• Missing or expired license (check license.json)

Next Steps

• Initial Setup: Create your admin account and configure your instance