Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
TrackerBot is a dual-service application designed as a Discord companion for TarkovTracker.org. It consists of a Discord bot interface and an Express-based web server that facilitates GitHub issue reporting. This guide outlines the necessary environment, configuration, and execution steps required to deploy both services successfully.
The application requires Node.js 18+ and uses ESM (ECMAScript Modules) throughout its architecture.
Sources: README.md:12, AGENTS.md:10
System Architecture
The project is structured to run two services side-by-side. The bot.js service handles Discord interactions such as slash commands and automated moderation, while webserver.js serves a public web portal for bug and data reports.
The diagram shows the relationship between environment configuration, the two internal services, and the external APIs they interact with.
Sources: AGENTS.md:6-10, README.md:20-25
Prerequisites and Installation
Deployment begins with installing the necessary dependencies using the Node Package Manager. The project relies on discord.js v14 for bot operations and express for the web server.
- Install Dependencies:
npm install - Node Version Requirement:
Ensure the environment is running Node.js version 18 or higher.
Sources: package.json:23-35, README.md:41-45
Environment Configuration
Both services depend on a central .env file for configuration. Environment variables are validated at startup. If required variables are missing, the application will throw an error and fail to start.
Required Discord Configuration
| Variable | Description |
|---|---|
DISCORD_TOKEN | The authentication token for the Discord Bot. |
ADMIN_ROLE_ID | Comma-separated Discord role IDs for admin-only commands. |
WELCOME_CHANNEL_ID | Channel ID where automated welcome messages are posted. |
AUTO_ROLE_ID_1-4 | Role IDs automatically assigned to new members. |
PANEL_ADMIN_ROLE_ID | Role ID required for panel administration commands. |
Required Web and GitHub Configuration
| Variable | Description |
|---|---|
GITHUB_TOKEN | PAT with repo or issues:write scope. |
REPO_DEV | Target repository for website bug reports. |
REPO_DATA_REPORT | Target repository for data-related issues. |
PORT | The port the web server listens on (default: 3000). |
ALLOWED_ORIGINS | Comma-separated list of origins for CORS validation. |
Sources: src/config/env.js:1-11, webserver.js:15-28, README.md:47-66
Execution Procedures
TrackerBot supports running both services concurrently or as isolated processes. This is managed via npm scripts defined in package.json.
This flowchart illustrates the initialization sequence for both services when starting the application.
Sources: package.json:7-12, bot.js:10-25, webserver.js:160-164
Deployment Commands
- Full Deployment:
npm start(Runs both bot and web server). - Bot Only:
npm run start:bot - Web Server Only:
npm run start:web
Sources: package.json:7-12, README.md:73-82
Network and Security
When deploying the web server behind a reverse proxy (e.g., Nginx or Cloudflare), the application must be configured to trust the proxy to ensure accurate rate limiting based on client IPs.
- Proxy Trust: The server uses
app.set("trust proxy", 1)to handle forwarded headers. - Rate Limiting: Separate limiters are applied to
/dataand/issueendpoints, allowing 5 submissions per minute per IP. - Origin Validation: The
checkOriginmiddleware enforces an allowlist of domains to prevent unauthorized form submissions. - Honeypot Protection: Forms include a hidden
companyfield; submissions containing data in this field are silently ignored to mitigate bot spam.
Sources: webserver.js:34-36, webserver.js:63-71, webserver.js:84-95, webserver.js:104-110
Verification and Maintenance
Before finalizing a deployment, the following checks should be performed to ensure system integrity:
- Syntax Validation: Run
node --check bot.jsandnode --check webserver.js. - Unit Tests: Run
npm testto execute the Node.js test suite, which includes environment validation and honeypot logic tests. - Health Check: The web server provides a
GET /healthendpoint that returns{ "status": "ok" }.
Sources: AGENTS.md:38-42, webserver.js:102, package.json:8
Summary
Deploying TrackerBot requires a Node.js 18+ environment and careful configuration of the .env file. By utilizing the concurrent start script, administrators can launch both the Discord automation and the GitHub-integrated bug reporting portal simultaneously. Security measures such as rate limiting, origin checking, and proxy trust should be verified if deploying in a production environment behind a reverse proxy.