Self-Hosted Deployment

Overview

Nexus Access Vault can be deployed as a self-hosted solution in your own infrastructure, giving you complete control over your data, security, and network configuration. This guide covers the complete deployment process from initial setup to production.

Prerequisites

Before deploying Nexus Access Vault, ensure you have:

Node.js

Node.js 18+ and npm installed (Install with nvm)

Supabase Project

Active Supabase project with project ID and anon key

Zitadel Instance

Zitadel OIDC provider configured for authentication

Network Access

Netbird VPN or similar for network isolation (optional but recommended)

Deployment Steps

Clone the Repository

Clone the Nexus Access Vault repository to your server:

git clone <YOUR_GIT_URL>
cd <YOUR_PROJECT_NAME>

Install Dependencies

Install all required npm packages:

npm install

Configure Environment Variables

Copy the example environment file and configure your settings:

cp .env.example .env

See Environment Variables for detailed configuration.

Set Up Database

Initialize your Supabase database with the required schema:

# Install Supabase CLI
npm install -g supabase

# Link to your project
supabase link --project-ref <your-project-id>

# Run migrations
supabase db push

See Database Setup for more details.

Configure Network Access (Optional)

For VPN-only access, configure Netbird or your network solution:

# Install Netbird
curl -fsSL https://pkgs.netbird.io/install.sh | sh

# Connect to your network
netbird up --setup-key <your-setup-key>

See Network Configuration for details.

Build the Application

Build the production-ready application:

npm run build

This creates optimized static files in the dist/ directory.

Start the Application

For development:

npm run dev

For production, use a process manager like PM2:

npm install -g pm2
npm run build
pm2 start npm --name "nexus-vault" -- run preview

Production Deployment Options

Option 1: Static Hosting

Since Nexus Access Vault is built with Vite, you can deploy the built static files to any static hosting service:

Deploy to Nginx

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/nexus-vault/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Enable gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}

Deploy with Apache

<VirtualHost *:80>
    ServerName your-domain.com
    DocumentRoot /path/to/nexus-vault/dist

    <Directory /path/to/nexus-vault/dist>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
        
        # Enable React Router
        RewriteEngine On
        RewriteBase /
        RewriteRule ^index\.html$ - [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.html [L]
    </Directory>
</VirtualHost>

Option 2: Node.js Server

Run the application using Node.js with the built-in preview server:

# Build the application
npm run build

# Install PM2 for process management
npm install -g pm2

# Start with PM2
pm2 start npm --name "nexus-vault" -- run preview

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

Option 3: Docker Deployment

Create a Dockerfile for containerized deployment:

# Build stage
FROM node:18-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine

COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Create nginx.conf:

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Build and run:

# Build the image
docker build -t nexus-vault:latest .

# Run the container
docker run -d -p 8080:80 --name nexus-vault nexus-vault:latest

Or use Docker Compose (docker-compose.yml):

version: '3.8'

services:
  nexus-vault:
    build: .
    ports:
      - "8080:80"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Server Configuration

Binding to Specific Network Interface

The default Vite configuration binds to all interfaces (::). For production, you may want to bind to a specific interface:

// vite.config.ts
export default defineConfig({
  server: {
    host: "your-netbird-ip",  // Bind to specific IP
    port: 8080,
  },
});

See vite.config.ts:8-11 for the default configuration.

Firewall Rules

For VPN-only access, configure your firewall to allow connections only from your VPN subnet:

# Example with ufw (Ubuntu)
sudo ufw allow from 100.64.0.0/10 to any port 8080
sudo ufw deny 8080

Health Checks and Monitoring

Application Health

Monitor your application with PM2:

# View application status
pm2 status

# View logs
pm2 logs nexus-vault

# Monitor resources
pm2 monit

Database Health

Monitor your Supabase database through the Supabase dashboard or CLI:

# Check database status
supabase db status

# View database logs
supabase logs db

SSL/TLS Configuration

For production deployments, always use HTTPS:

Let's Encrypt
Self-Signed Certificate

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal is configured automatically
sudo certbot renew --dry-run

# Generate self-signed certificate
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout /etc/ssl/private/nexus-vault.key \
  -out /etc/ssl/certs/nexus-vault.crt

# Configure Nginx to use the certificate
# Update your nginx.conf with ssl_certificate and ssl_certificate_key

Backup and Recovery

Database Backups

Supabase automatically backs up your database. You can also create manual backups:

# Create a database dump
supabase db dump -f backup.sql

# Restore from backup
supabase db reset
psql -h db.your-project.supabase.co -U postgres -d postgres -f backup.sql

Application Backups

Backup your configuration files:

# Backup environment variables
cp .env .env.backup

# Backup custom configurations
tar -czf config-backup.tar.gz .env vite.config.ts

Troubleshooting

Application won't start

Check that all environment variables are set correctly
Verify Node.js version is 18 or higher: node --version
Check for port conflicts: lsof -i :8080
Review application logs: pm2 logs nexus-vault

Cannot connect to database

Verify Supabase project ID and URL are correct
Check that Supabase API key has not expired
Ensure database migrations have been run: supabase db status
Test connection: supabase db ping

Authentication not working

Verify Zitadel issuer URL is accessible
Check that redirect URI matches the configured value
Ensure client ID is correct
Review browser console for OIDC errors

VPN access issues

Verify Netbird is connected: netbird status
Check firewall rules allow traffic from VPN subnet
Ensure application is bound to correct interface
Test connectivity: curl http://netbird-ip:8080

Updating Your Deployment

To update your deployment to a new version:

Backup Current Installation

# Backup database
supabase db dump -f backup-$(date +%Y%m%d).sql

# Backup configuration
cp .env .env.backup

Pull Latest Changes

git fetch origin
git pull origin main

Update Dependencies

npm install

Run New Migrations

supabase db push

Rebuild and Restart

npm run build
pm2 restart nexus-vault

Next Steps

Environment Variables

Configure all environment variables for your deployment

Database Setup

Set up and migrate your Supabase database

Network Configuration

Configure VPN-only access with Netbird

Authentication

Set up Zitadel OIDC authentication

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

Overview

Prerequisites

Node.js

Supabase Project

Zitadel Instance

Network Access

Deployment Steps

Production Deployment Options

Option 1: Static Hosting

Option 2: Node.js Server

Option 3: Docker Deployment

Server Configuration

Binding to Specific Network Interface

Firewall Rules

Health Checks and Monitoring

Application Health

Database Health

SSL/TLS Configuration

Backup and Recovery

Database Backups

Application Backups

Troubleshooting

Updating Your Deployment

Next Steps

Environment Variables

Database Setup

Network Configuration

Authentication

Build docs developers (and LLMs) love

Overview

Getting Started

Authentication & SSO

Core Features

Network & Infrastructure

Administration

Deployment

​Overview

​Prerequisites

Node.js

Supabase Project

Zitadel Instance

Network Access

​Deployment Steps

​Production Deployment Options

​Option 1: Static Hosting

​Option 2: Node.js Server

​Option 3: Docker Deployment

​Server Configuration

​Binding to Specific Network Interface

​Firewall Rules

​Health Checks and Monitoring

​Application Health

​Database Health

​SSL/TLS Configuration

​Backup and Recovery

​Database Backups

​Application Backups

​Troubleshooting

​Updating Your Deployment

​Next Steps

Environment Variables

Database Setup

Network Configuration

Authentication

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Steps

Production Deployment Options

Option 1: Static Hosting

Option 2: Node.js Server

Option 3: Docker Deployment

Server Configuration

Binding to Specific Network Interface

Firewall Rules

Health Checks and Monitoring

Application Health

Database Health

SSL/TLS Configuration

Backup and Recovery

Database Backups

Application Backups

Troubleshooting

Updating Your Deployment

Next Steps