Installation

Prerequisites

Hub uses better-sqlite3 (native addon) for storage. On most platforms, prebuilt binaries install automatically via npm install. If compilation fails, ensure you have build tools installed (Xcode CLI on macOS, build-essential on Linux).

Clone the repository

git clone https://github.com/vaagatech/snapline-hub.git
cd snapline-hub

Snapline Hub is a standalone repository. It is not an npm package and is not published to the npm registry. You run it from source.

Install dependencies

npm install

This installs:

• Runtime: Express, better-sqlite3, cors, uuid
• Dev/build: TypeScript, Vite, React, Vitest, tsx

Development mode

Development runs two processes concurrently:

npm run dev

Open http://localhost:5173 in your browser. API requests from the UI are proxied to the backend automatically.

Run API or UI separately

npm run dev:server   # API only on :3847
npm run dev:web      # UI only on :5173 (requires API running)

Production build

For a single-process deployment, build the React UI and compile the TypeScript server:

npm run build
npm start

This:

1. Builds the React app into web/dist/
2. Compiles the server into dist/server/
3. Starts the server on port 3847, serving both API and static UI

Open http://localhost:3847 (or your configured PORT).

Build scripts reference

Environment variables

Example: secured team deployment

HOST=0.0.0.0 PORT=3847 \
HUB_API_KEY=your-secret-key \
ALLOWED_ORIGINS=https://hub.yourcompany.com \
SNAPLINE_HUB_DB=/var/lib/snapline-hub/reports.db \
npm start

Test runners push with the same key:

SNAPLINE_HUB_URL=https://hub.yourcompany.com \
SNAPLINE_HUB_API_KEY=your-secret-key \
npm test

Example: custom port and database path

PORT=8080 SNAPLINE_HUB_DB=/var/lib/snapline-hub/reports.db npm start

Verify installation

1. Health check

curl http://localhost:3847/api/health

Expected response:

{ "status": "ok", "reports": 0 }

2. Run tests

npm test

API integration tests validate ingest, list, retrieve, stats aggregation, pagination, API key auth, delete, and validation.

3. Open the UI

After npm run dev or npm start, open the dashboard. An empty state prompts you to upload a report or set SNAPLINE_HUB_URL in your Snapline test runner.

Deployment options

Local / team server

Run Hub on a machine your team can reach. Set SNAPLINE_HUB_URL in CI and developer environments to point at that server.

# On the server
git clone https://github.com/vaagatech/snapline-hub.git
cd snapline-hub
npm install
npm run build
PORT=3847 SNAPLINE_HUB_DB=/data/snapline-hub.db npm start

Use a process manager (systemd, PM2, Docker) to keep the process running across restarts.

systemd example

[Unit]
Description=Snapline Hub
After=network.target

[Service]
Type=simple
User=snapline
WorkingDirectory=/opt/snapline-hub
Environment=PORT=3847
Environment=SNAPLINE_HUB_DB=/var/lib/snapline-hub/data.db
ExecStart=/usr/bin/node dist/server/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target

Reverse proxy (nginx)

Place Hub behind nginx or another reverse proxy for TLS and authentication at the edge:

location / {
    proxy_pass http://127.0.0.1:3847;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Then set SNAPLINE_HUB_URL=https://hub.yourcompany.com in test runners.

CI pipeline

Hub is typically not run inside CI. Instead, CI pushes reports to a long-running Hub instance after tests complete. See CI integration.

Publishing this documentation

This documentation site deploys to GitHub Pages automatically when docs/ changes are pushed to main.

1. Open repository Settings → Pages
2. Set Source to GitHub Actions
3. Push to main — workflow Deploy documentation to GitHub Pages runs

Published URL: https://vaagatech.github.io/snapline-hub/

Local preview: npx serve docs from the repo root.