Files
discord-github-ticket-relay/docs/DEPLOYMENT.md

8.8 KiB
Raw Permalink Blame History

Deployment

Runs on a single Linux host with Node.js, PM2 and a TLS reverse proxy. State lives in one SQLite file. No external database or container runtime is required.

Processes

PM2 app Entry Instances Role
ticket-relay-web dist/index.js 1 Admin console, Discord interactions endpoint, OAuth callbacks. Binds PORT. Makes the first filing attempt right after acknowledging Discord.
ticket-relay-worker dist/worker.js 2 (configurable) Claims queued submissions, retries, reconciles uncertain results, housekeeping. No port.
ticket-relay-triage dist/triage-worker.js 1 Optional AI triage of tickets that are already filed, and the issue sync: a copy of every issue in the connected repositories (GitHub issues), refreshed every couple of minutes, that triage searches for duplicates. Never touches the filing queue, so stopping it or Claude being down can't affect filing.

All processes share DATABASE_PATH. Every process applies pending migrations on boot; the runner holds SQLite's write lock, so simultaneous starts are safe.

Requirements: Node.js ≥ 22 (with build tools for better-sqlite3 if no prebuilt binary matches), PM2, a domain with TLS, local disk for the database. Network filesystems are not supported by SQLite.

Install

Host install (PM2)

git clone <repo> ticket-relay && cd ticket-relay
npm ci
npm run build
cp .env.example .env          # see Configuration
npm install -g pm2
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup                   # run the printed command to start on boot

Container install (Docker / Kubernetes)

Images are published to ghcr.io/storytold/discord-github-ticket-relay and docker.io/storytold/discord-github-ticket-relay using Docker Hardened Images (dhi.io/node:24) for minimal surface and non-root execution (UID 1000).

Persistent state (SQLite database and ticket file attachments) lives in /app/data. Mount a persistent volume to /app/data.

docker run -d \
  --name ticket-relay \
  -p 3000:3000 \
  -v ticket-relay-data:/app/data \
  --env-file .env \
  ghcr.io/storytold/discord-github-ticket-relay:latest

The image has no secrets/ folder: leave GITHUB_APP_PRIVATE_KEY_FILE empty and set GITHUB_APP_PRIVATE_KEY to the key as one line (base64 -w0 sec.pem).

In Kubernetes or clustered setups, you can run all-in-one or scale workers independently:

  • Web (Admin + Discord + OAuth): ENTRYPOINT ["node"] CMD ["dist/index.js"] (set RUN_WORKER=false and RUN_TRIAGE=false if scaling workers in separate pods).
  • Queue Workers: args: ["dist/worker.js"]
  • Triage Worker: args: ["dist/triage-worker.js"]

Reverse proxy

Terminate TLS and forward to 127.0.0.1:3000. Caddy example (automatic certificates):

tickets.example.com {
    reverse_proxy 127.0.0.1:3000
}

Set HOST=127.0.0.1 and TRUST_PROXY=true in .env. Verify with curl https://tickets.example.com/healthz.

Public endpoints

Route Caller
POST /discord/interactions Discord (Ed25519-signed)
GET /oauth/discord/callback Browser, after Discord OAuth
GET /oauth/github/callback Browser, after GitHub App install/authorize
POST /github/webhook GitHub (HMAC-signed, optional)
POST /mcp Coding agents (personal bearer token; only while MCP is on in the workspace)
GET /healthz Monitoring
/* Admin console

Configuration

.env in the app directory (see .env.example):

Variable Notes
DATABASE_PATH SQLite file. Default ./data/ticket-relay.db; directory is created.
PUBLIC_URL https://tickets.example.com
ENCRYPTION_KEY openssl rand -base64 32. Encrypts stored tokens and ticket text (AES-256-GCM). Changing it makes existing encrypted data unreadable.
DISCORD_*, GITHUB_* Provider credentials, see PROVIDER_SETUP.md
PLATFORM_ADMIN_DISCORD_IDS Your Discord user ID, so nobody else can claim the deployment
HOST, TRUST_PROXY 127.0.0.1, true behind a proxy
WORKER_CONCURRENCY Parallel filings per worker process (set in ecosystem.config.cjs, default 2)

All other configuration is stored in the database and managed in the console.

Operations

Task Command
Deploy update git pull && npm ci && npm run build && pm2 reload ecosystem.config.cjs
Status pm2 status
Logs pm2 logs ticket-relay-web / pm2 logs ticket-relay-worker
Scale workers pm2 scale ticket-relay-worker 4
Backup (online) sqlite3 data/ticket-relay.db ".backup 'backups/relay-$(date +%F).db'"
Backup files tar czf backups/files-$(date +%F).tgz -C data files (screenshots attached to tickets)
Restore pm2 stop all, replace the database file (remove -wal/-shm), pm2 start all

Keep the .env (especially ENCRYPTION_KEY) alongside database backups. A backup can't be decrypted without it.

Attached files live in FILES_DIR (default data/files). They're served at /f/<id> through the web process, so no Caddy change is needed. A file deleted in the console (or by the cleanup rules in Discord tickets › Files) is gone from disk right away, but stays in older backups until they rotate out.

Server health

Each process reports its memory, CPU and event-loop delay every 30 seconds. The Server health page in the console shows them live (with 24-hour charts, restarts, disk, the GitHub API rate limit and alerts). The limit shown comes from MEMORY_LIMIT_MB in ecosystem.config.cjs; keep it equal to that app's max_memory_restart when you change one.

Scaling

  • Queue safety. Workers claim a submission with a single atomic UPDATE … RETURNING under SQLite's write lock and hold a 90s lease, so a ticket is filed by exactly one process. A crashed worker's ticket is picked up after the lease expires and reconciled, never re-sent blindly.
  • Throughput. GitHub limits issue creation per app to roughly 80/min and 500/h, with about 1s spacing recommended. Two workers with concurrency 2 already exceed what GitHub accepts; more workers add redundancy, not speed. Over the limit, tickets wait in the queue and retry automatically.
  • Single host. SQLite needs local disk, so all processes run on one machine. Keep exactly one ticket-relay-web instance (it owns the port); scale ticket-relay-worker freely.

Data retention

Housekeeping runs in every worker every 10 minutes:

  • The description is dropped once the issue exists; only the title stays for history.
  • Created and closed submissions lose stored text after the workspace retention period (default 30 days). Failed and uncertain ones keep it for at least 90 days.
  • Expired sessions, OAuth states and Discord interaction tokens are deleted.
  • Moderation › Ticket management keeps an encrypted copy of each GitHub issue a moderator opens (its text and comments), so it shows at once. A copy is deleted 30 days after it was last read.

MCP

POST /mcp lets the team's coding agents (Claude Code, Cursor, VS Code, Codex) work with tickets. It runs in ticket-relay-web; nothing else to deploy, and the proxy needs no change.

  • Off by default. An admin turns it on under MCP in the console; turning it off cuts every agent off on its next call.
  • Tokens. Each person makes their own (one per device) on the MCP page. A token is shown once and only its SHA-256 hash is stored. Tokens expire (30, 90 or 365 days; admins can make one that doesn't), are Read & write or Read only (people with only read tools always get Read only), and are revoked by their owner or an admin, or when the person is removed from the workspace.
  • Docs. The MCP page's Docs tab explains setup, every tool, claims and what to do when something's wrong.
  • Access. Every call checks the token, that MCP is on and the person's current access: each tool is a switch per moderator in Members & permissions, in Read and Write groups (owners and admins have all of them). Actions on GitHub use the app's existing permissions, the admins' close reasons and saved replies, and are logged in the Mod log as done by that person through MCP.
  • Limits. Per token: 240 requests, 120 tool calls and 20 changes a minute. Requests from a web page on another origin are refused. Tool calls are logged with the tool, person and time, never their arguments.
  • Claims ("I'm on it") are kept in Ticket Relay only, and end when released, when the ticket closes, or after 3 days unread without an open pull request.

Logging

pino JSON to stdout, collected by PM2. Request URLs are logged without query strings, auth and cookie headers are stripped, and ticket text and tokens are never logged. Processing logs include the submission reference, repository, outcome code and HTTP status, so you can trace a ticket alongside its timeline in the console.