Self-Hosting

Self-hosting RichView means running your own API server and web editor. You get report storage in a local SQLite database, user accounts with OAuth login, and the ability to publish reports to URLs you control.

If you only need to generate HTML files from the command line, you don't need to self-host. The CLI works standalone. Self-hosting is for teams that want the full web editor experience on their own infrastructure.

What you get

• Web editor at http://localhost:3000 -- create and edit reports visually with live preview
• API server at http://localhost:4400 -- report storage, user auth, WebSocket collaboration
• SQLite database -- all data stored in a single file, easy to back up
• Published reports -- share reports via URL from your own server

Docker Compose (recommended)

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• 512MB RAM, 1GB disk

Quick start

git clone https://github.com/richview-universe/richview-v2.git
cd richview-v2

# Create environment file
cp .env.example .env
echo "RV_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

# Build the web SPA, then start everything
pnpm install && pnpm build
docker compose up -d richview-server
docker compose cp packages/web/dist/. richview-web:/srv/
docker compose up -d richview-web

Health check

curl http://localhost:4400/health
# {"status":"ok","version":"0.0.1"}

Backups

The SQLite database lives in a Docker volume. To back it up while the server is running:

docker compose exec richview-server cp /data/richview.db /data/richview-backup.db
docker compose cp richview-server:/data/richview-backup.db ./richview-backup.db

Running without Docker

If you prefer to run directly with Node.js:

git clone https://github.com/richview-universe/richview-v2.git
cd richview-v2
pnpm install
pnpm build

# Start the API server and web editor together
pnpm dev

This starts:

• API server at http://localhost:4400
• Web editor at http://localhost:5173

OAuth login

User authentication requires OAuth credentials. Set these environment variables before starting the server:

Variable	Description
GITHUB_CLIENT_ID	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	GitHub OAuth app client secret
GITHUB_REDIRECT_URI	Callback URL (e.g., http://localhost:4400/api/oauth/github/callback)
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret
GOOGLE_REDIRECT_URI	Callback URL (e.g., http://localhost:4400/api/oauth/google/callback)

Without OAuth credentials, the editor still works for local report creation and preview. Login is only needed for saving reports to the server and publishing.

Environment variables

Variable	Required	Default	Description
PORT	No	4400	Server HTTP port
DB_PATH	No	richview.db	SQLite database file path
RV_ENCRYPTION_KEY	Yes	--	64-char hex key for encrypting credentials. Generate with openssl rand -hex 32
BASE_URL	No	--	Public URL of the app (used for OAuth redirects)
NODE_ENV	No	--	Set to production in deployed environments

Database Management

The richview db CLI manages your self-hosted database remotely. Point it at your server with --server or the RICHVIEW_SERVER environment variable.

# View database statistics
richview db stats --server https://reports.example.com

# Remove test/orphan reports (dry run, then delete)
richview db clean --server https://reports.example.com
richview db clean --server https://reports.example.com --force

# Reclaim disk space after deletions
richview db vacuum --server https://reports.example.com

These commands require RICHVIEW_API_KEY to be set for authentication.

Reverse Proxy Configuration

In production, put a reverse proxy in front of the API server and web editor. The Docker Compose setup uses Caddy, but nginx works too.

Caddy

reports.example.com {
    handle /api/* {
        reverse_proxy richview-server:4400
    }
    handle {
        root * /srv
        try_files {path} /index.html
        file_server
    }
}

nginx

server {
    listen 80;
    server_name reports.example.com;

    location /api/ {
        proxy_pass http://localhost:4400;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support for collaboration
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location / {
        root /srv/richview-web;
        try_files $uri $uri/ /index.html;
    }
}

Architecture

        Your domain (or localhost)
                   |
      ┌────────────┴────────────┐
      |                         |
   /*  (static)           /api/*  (proxy)
   Web Editor (React)     API Server (Hono)
   Caddy / nginx          Port 4400
                                |
                          /data/richview.db
                         (SQLite, WAL mode)

SQLite is a single-writer database. This means one server instance, one region. For RichView's expected load (hundreds of concurrent users), this is more than enough. If you need horizontal scaling, migrate to PostgreSQL.

Production deployment

For deploying to cloud infrastructure (Cloudflare Pages, Fly.io), see the Deployment Guide.