@argus-vrt/web

CLI tool for deploying and managing the Argus web dashboard.

The Argus web dashboard is a self-hosted review interface for visual regression test results — similar to Chromatic, but self-hosted. This package provides an interactive CLI to set up and manage the dashboard via Docker.

Quick Start

# Run the interactive setup wizard
npx @argus-vrt/web init

# Start the dashboard
npx @argus-vrt/web start

# Open http://localhost:3000

The init wizard generates a docker-compose.yml, .env, and optionally nginx.conf in an ./argus/ directory.

Prerequisites

• Docker installed and running
• Node.js >= 20 (for running the CLI via npx)
• A GitHub OAuth App for authentication

Authentication

Argus requires GitHub OAuth for login. All browser routes are protected — unauthenticated users are redirected to GitHub to sign in.

The /api/upload endpoint used by CI/CD is authenticated separately via API key (Authorization: Bearer <key> header), so pipelines don't need GitHub credentials.

Setting Up GitHub OAuth

1. Go to GitHub Developer Settings → New OAuth App
2. Set the Authorization callback URL to https://your-domain.com/auth/github/callback (or http://localhost:3000/auth/github/callback for local development)
3. Save the Client ID and generate a Client Secret
4. Provide these values when running npx @argus-vrt/web init

Commands

npx @argus-vrt/web init

Interactive setup wizard. Prompts for:

• PostgreSQL — include a container (recommended) or use an external instance
• Port — default 3000
• Domain — custom domain or localhost
• HTTPS — Let's Encrypt, custom certificate, or none
• Reverse proxy — include an Nginx container or manage yourself
• Screenshots path — where uploaded screenshots are stored
• GitHub Client ID — from your GitHub OAuth App
• GitHub Client Secret — from your GitHub OAuth App
• API key — for CI/CD uploads (auto-generated by default)

A session secret is auto-generated and does not require input.

Generates configuration files into ./argus/ (or --dir <path>).

npx @argus-vrt/web start

Start Argus containers (docker compose up -d).

npx @argus-vrt/web stop

Stop Argus containers (docker compose down).

npx @argus-vrt/web logs

Stream container logs (docker compose logs -f).

npx @argus-vrt/web logs --service web    # only web container
npx @argus-vrt/web logs --service db     # only database

npx @argus-vrt/web status

Show container status and run a health check on the web dashboard.

npx @argus-vrt/web upgrade

Pull the latest Docker images and restart containers.

npx @argus-vrt/web setup-ssl <domain>

Obtain a Let's Encrypt SSL certificate for your domain. Requires the Nginx and Certbot containers (select Let's Encrypt during init).

npx @argus-vrt/web setup-ssl argus.yourcompany.com

Options

All management commands (start, stop, logs, status, upgrade, setup-ssl) accept:

| Flag | Description | |------|-------------| | -d, --dir <path> | Path to the Argus directory (default: ./argus) |

Connecting the CLI

Once the dashboard is running, point the testing CLI at it by adding apiUrl and apiKey to your project's .argus.json:

{
  "apiUrl": "http://localhost:3000",
  "apiKey": "your-api-key-from-init"
}

Then upload results after running tests:

npx argus test

Or upload manually with a header:

curl -X POST https://your-domain.com/api/upload \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main","commitHash":"abc123","stories":[...]}'

Environment Variables

The generated .env file includes:

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Server port | | DATABASE_URL | (auto) | PostgreSQL connection string (external DB only) | | DB_PASSWORD | argus | Database password (container DB only) | | SCREENSHOTS_PATH | ./argus-data/images | Path to screenshots directory | | GITHUB_CLIENT_ID | — | GitHub OAuth App client ID | | GITHUB_CLIENT_SECRET | — | GitHub OAuth App client secret | | SESSION_SECRET | (auto-generated) | Encryption key for session cookies | | ARGUS_API_KEY | (auto-generated) | API key for CI/CD upload authentication |

Docker Image

The web dashboard is distributed as a Docker image on GitHub Container Registry:

ghcr.io/maxcwolf/argus-web:latest

License

MIT