Configure the Capinetta RP Bot System's Environment

All runtime configuration for the Capinetta RP Bot System lives in a single .env file at the project root. This file drives every moving part: the two bot tokens, the MariaDB connection string, Discord OAuth2 credentials for the web dashboard, optional Redis caching, HTTPS termination, Discord webhook alerts, monitoring thresholds, cache TTLs, and ticket behaviour timers. The file is validated at startup by config.js — if any required variable is absent, the process logs a fatal error listing the missing keys and exits before attempting to connect to Discord or the database. Start by copying the provided example file:

cp .env.example .env

Then open .env in your editor and work through each section below.

Never commit your .env file to version control. It contains secret tokens and credentials. The repository’s .gitignore already excludes it, but always double-check before pushing — especially if you fork the project.

Required Variables

These eight variables are checked by config.js on every startup. The bot will not start if any of them are missing or empty.

GENERAL_TOKEN

string

required

Discord bot token for the Bot General process (capinetta-general). Obtain it from the Discord Developer Portal under your application’s Bot tab → Reset Token. Keep this value secret — it grants full API access as the bot.

WHITELIST_TOKEN

string

required

Discord bot token for the Bot Whitelist process (capinetta-whitelist). Created the same way as GENERAL_TOKEN but from a separate Discord application. Both tokens are validated at startup.

GENERAL_CLIENT_ID

string

required

OAuth2 Client ID used by the web dashboard to initiate the Discord login flow. Found in the Discord Developer Portal under your General Bot application → OAuth2 → Client ID.

GENERAL_CLIENT_SECRET

string

required

OAuth2 Client Secret for the web dashboard. Located next to the Client ID in the Discord Developer Portal → OAuth2 → Client Secret. Regenerate it there if you lose it.

DASHBOARD_CALLBACK_URL

string

required

The full URL Discord redirects users back to after they authenticate. Must exactly match one of the Redirects registered in the Discord Developer Portal → OAuth2.

http://localhost:3000/auth/discord/callback

In production, replace localhost:3000 with your actual domain (e.g. https://dashboard.capinettarp.com.ar/auth/discord/callback).

SESSION_SECRET

string

required

A long, random string used by Express to sign and verify session cookies. Generate a cryptographically secure value with:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Store the output in this variable and never reuse it across environments.

GENERAL_GUILD_ID

string

required

The Discord server (guild) ID for your main community. Used to scope slash command deployment and per-guild settings. Enable Developer Mode in Discord (Settings → Advanced), then right-click your server icon and select Copy Server ID.

DATABASE_URL

string

required

Full MariaDB/MySQL connection string in Prisma format:

mysql://USER:PASSWORD@localhost:3306/DB_NAME

Replace USER, PASSWORD, and DB_NAME with your actual credentials. The database must already exist before running npx prisma db push.

Generate a strong SESSION_SECRET before your first deployment and store it somewhere safe (e.g. a password manager). If you rotate it, all existing user sessions are immediately invalidated and users must log in again.

Whitelist Variables

These variables configure the Bot Whitelist process and are read at startup from config.whitelist in config.js.

WHITELIST_CLIENT_ID

string

OAuth2 Client ID for the Whitelist Bot application. Used when deploying whitelist slash commands via npm run deploy:whitelist.

WHITELIST_GUILD_ID

string

Discord server ID where whitelist applications are processed. Can be the same as GENERAL_GUILD_ID or a separate staff-only server.

WHITELIST_STAFF_ROLE_ID

string

Role ID of the Discord role whose members are permitted to run /aprobar and /rechazar. Right-click the role in Discord (Server Settings → Roles) with Developer Mode enabled to copy its ID.

WHITELIST_CHANNEL_ID

string

Channel ID where whitelist decision embeds are posted after a staff member approves or rejects an application. The bot must have Send Messages permission in this channel.

General Bot Channel & Role Variables

These variables are read by config.general in config.js and configure the operational channels and roles used by Bot General. All are optional — the bot starts without them, but features that depend on them (welcome cards, audit logs, role restoration) will be silently skipped until they are set.

GENERAL_WELCOME_CHANNEL

string

Channel ID where the Canvas welcome card is posted whenever a new member joins the server. The bot must have Send Messages and Attach Files permissions in this channel.

GENERAL_LOGS_CHANNEL

string

Channel ID for audit log events — message edits/deletions, role changes, bans, voice activity, and member updates are posted here.

GENERAL_VERIFY_CHANNEL

string

Channel ID where the verification button panel (posted by /set-verify) is displayed. If omitted, the verification system will not function.

GENERAL_ROLE_NO_VERIFY

string

Role ID assigned to members who have not yet verified. The anti-bot system and the verification button use this role to identify unverified users.

GENERAL_ROLE_USER

string

Role ID granted to members after they complete verification. The /unmute command also restores this role as part of the full role set stored in the database.

GENERAL_ROLE_MUTED

string

Role ID applied by the anti-spam system when a user is moved to the isolation zone. The bot saves the user’s previous roles to MariaDB before applying this role, so /unmute can fully restore them.

GENERAL_SUPPORT_SCAM_CHANNEL

string

Channel ID of a dedicated warning channel where scam-related support alerts are posted. Used by the informational support message sent via /set-support.

Optional Variables

These variables enhance the system but fall back to safe defaults if omitted.

Redis Cache

REDIS_HOST

string

default:"localhost"

Hostname or IP address of the Redis server. If Redis is unavailable or these variables are not set, the dashboard automatically falls back to an in-memory cache.

REDIS_PORT

number

default:"6379"

TCP port Redis is listening on.

REDIS_PASSWORD

string

Password for Redis authentication. Leave empty if your Redis instance does not require a password (common in local development).

HTTPS

HTTPS_ENABLED

boolean

default:"false"

Set to true to enable HTTPS on the Express dashboard server. Requires SSL_KEY_PATH and SSL_CERT_PATH to point to valid certificate files.

SSL_KEY_PATH

string

default:"./certs/key.pem"

Filesystem path to your TLS private key file. Only read when HTTPS_ENABLED=true.

SSL_CERT_PATH

string

default:"./certs/cert.pem"

Filesystem path to your TLS certificate file. Only read when HTTPS_ENABLED=true.

Integrations

FIVEM_BASE_URL

string

Base URL of your FiveM game server’s HTTP endpoints (e.g. info.json and players.json). Used to display live server statistics on the dashboard.Example from .env.example:

FIVEM_BASE_URL=http://desarrollo.capinettarp.com.ar:10000

ALERTS_WEBHOOK_URL

string

Discord webhook URL that receives automated system alert notifications when monitoring thresholds are breached. Format:

https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN

PORT

number

default:"3000"

HTTP port the Express dashboard listens on. Change this if port 3000 is already in use on your host.

Monitoring Thresholds

These variables configure the automated alerting system. When a metric exceeds its threshold, an alert is sent to ALERTS_WEBHOOK_URL. All values are read and parsed by config.monitoring in config.js.

ALERT_ERROR_RATE

number

default:"5"

HTTP error response percentage that triggers an alert. Default: 5 (5% of requests returning 4xx/5xx errors).

ALERT_CACHE_HIT_RATE

number

default:"60"

Minimum acceptable cache hit rate percentage. An alert fires when the hit rate drops below this value. Default: 60 (60%).

ALERT_SLOW_QUERIES

number

default:"10"

Maximum number of slow database queries before an alert is raised. Default: 10.

ALERT_MEMORY_USAGE

number

default:"85"

Maximum process memory usage percentage before an alert fires. Default: 85 (85%).

ALERT_DISCORD_RATE_LIMIT

number

default:"5"

Maximum number of Discord API rate-limit responses before an alert is sent. Default: 5.

ALERT_RESPONSE_TIME

number

default:"1000"

Maximum average HTTP response time in milliseconds before an alert triggers. Default: 1000 (1 second).

Cache TTL Variables

These variables tune how long data lives in the Redis (or in-memory) cache. All values are in milliseconds and are read by config.cache in config.js.

CACHE_USER_PROFILE_TTL

number

default:"600000"

How long a user profile is considered fresh in the cache before being evicted. Default: 600000 (10 minutes).

CACHE_USER_PROFILE_REFRESH

number

default:"900000"

Interval at which the background job refreshes cached user profiles in batches. Default: 900000 (15 minutes).

CACHE_USER_PROFILE_BATCH

number

default:"50"

Number of user profiles the background refresh job processes per batch cycle. Keeping this value low avoids Discord API rate limits during large bulk refreshes. Default: 50.

CACHE_USER_PROFILE_MAX_SIZE

number

default:"1000"

Maximum number of user profiles stored in the in-memory cache at once. When the limit is reached, the oldest entries are evicted. Default: 1000.

CACHE_STATS_TTL

number

default:"300000"

Time-to-live for server statistics data shown on the dashboard. Default: 300000 (5 minutes).

CACHE_DISCORD_METRICS_TTL

number

default:"45000"

Time-to-live for Discord-specific metrics (member counts, online status, etc.). Kept short for near-real-time accuracy. Default: 45000 (45 seconds).

LOGS_CLEANUP_INTERVAL

number

default:"86400000"

How often the background job runs to purge audit log entries that exceed the retention window. Default: 86400000 (1 day).

LOGS_RETENTION_DAYS

number

default:"30"

Number of days audit log entries are kept before the cleanup job deletes them. Default: 30 (30 days).

API Variables

API_MEMBER_FETCH_COOLDOWN

number

default:"30000"

Minimum time in milliseconds between successive Discord API calls to fetch guild member data. This cooldown prevents hitting Discord’s rate limits when the dashboard or background jobs request member profiles in quick succession. Default: 30000 (30 seconds).

Ticket Behaviour Variables

These variables control timing within the ticket lifecycle and are read by config.tickets in config.js. All values are in milliseconds.

TICKET_INACTIVITY_WARNING

number

default:"1800000"

Time after the last message in a ticket before the first inactivity reminder is sent to staff. Default: 1800000 (30 minutes).

TICKET_INACTIVITY_RETRY

number

default:"3600000"

Time after the first inactivity reminder before a second (final) reminder is sent if there is still no response. Default: 3600000 (60 minutes).

TICKET_CLOSE_TIMEOUT

number

default:"5000"

Duration the close-confirmation button remains active after a staff member initiates ticket closure. Default: 5000 (5 seconds).

Full `.env.example` Reference

For convenience, here is the complete annotated example shipped with the repository:

# === TOKENS DE LOS BOTS ===
GENERAL_TOKEN=TU_TOKEN_BOT_GENERAL_AQUI
WHITELIST_TOKEN=TU_TOKEN_BOT_WHITELIST_AQUI

# === OAUTH2 (Dashboard Web) ===
GENERAL_CLIENT_ID=TU_CLIENT_ID_AQUI
GENERAL_CLIENT_SECRET=TU_CLIENT_SECRET_AQUI
DASHBOARD_CALLBACK_URL=http://localhost:3000/auth/discord/callback
SESSION_SECRET=GENERA_UN_STRING_ALEATORIO_SEGURO_AQUI

# === IDENTIFICACIÓN ===
GENERAL_GUILD_ID=ID_TU_SERVIDOR_PRINCIPAL
WHITELIST_CLIENT_ID=ID_BOT_WHITELIST
WHITELIST_GUILD_ID=ID_TU_SERVIDOR_WHITELIST

# === WHITELIST ===
WHITELIST_STAFF_ROLE_ID=ID_ROL_STAFF_WHITELIST
WHITELIST_CHANNEL_ID=ID_CANAL_RESULTADOS_WHITELIST

# === BOT GENERAL — CANALES Y ROLES ===
GENERAL_WELCOME_CHANNEL=ID_CANAL_BIENVENIDA
GENERAL_LOGS_CHANNEL=ID_CANAL_LOGS
GENERAL_VERIFY_CHANNEL=ID_CANAL_VERIFICACION
GENERAL_ROLE_NO_VERIFY=ID_ROL_SIN_VERIFICAR
GENERAL_ROLE_USER=ID_ROL_USUARIO_VERIFICADO
GENERAL_ROLE_MUTED=ID_ROL_AISLADO
GENERAL_SUPPORT_SCAM_CHANNEL=ID_CANAL_SOPORTE_SCAM

# === BASE DE DATOS (MariaDB/MySQL) ===
DATABASE_URL="mysql://USUARIO:PASSWORD@localhost:3306/NOMBRE_BD"

# === REDIS (Opcional) ===
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# === HTTPS (Producción) ===
HTTPS_ENABLED=false
SSL_KEY_PATH=./certs/key.pem
SSL_CERT_PATH=./certs/cert.pem

# === WEBHOOKS ===
ALERTS_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN

# === FIVEM ===
FIVEM_BASE_URL=http://desarrollo.capinettarp.com.ar:10000

# === UMBRALES DE ALERTAS ===
ALERT_ERROR_RATE=5
ALERT_CACHE_HIT_RATE=60
ALERT_SLOW_QUERIES=10
ALERT_MEMORY_USAGE=85
ALERT_DISCORD_RATE_LIMIT=5
ALERT_RESPONSE_TIME=1000

# === CONFIGURACIÓN DE CACHÉ ===
CACHE_USER_PROFILE_TTL=600000
CACHE_USER_PROFILE_REFRESH=900000
CACHE_USER_PROFILE_BATCH=50
CACHE_USER_PROFILE_MAX_SIZE=1000
CACHE_STATS_TTL=300000
CACHE_DISCORD_METRICS_TTL=45000
LOGS_CLEANUP_INTERVAL=86400000
LOGS_RETENTION_DAYS=30

# === API ===
API_MEMBER_FETCH_COOLDOWN=30000

# === TICKETS ===
TICKET_INACTIVITY_WARNING=1800000
TICKET_INACTIVITY_RETRY=3600000
TICKET_CLOSE_TIMEOUT=5000

Get Started

Core Features

Deployment

Reference

Contributing

Configure the Capinetta RP Bot System's Environment

Required Variables

Whitelist Variables

General Bot Channel & Role Variables

Optional Variables

Redis Cache

HTTPS

Integrations

Monitoring Thresholds

Cache TTL Variables

API Variables

Ticket Behaviour Variables

Full `.env.example` Reference

Build docs developers (and LLMs) love

Get Started

Core Features

Deployment

Reference

Contributing

Documentation Index

​Required Variables

​Whitelist Variables

​General Bot Channel & Role Variables

​Optional Variables

​Redis Cache

​HTTPS

​Integrations

​Monitoring Thresholds

​Cache TTL Variables

​API Variables

​Ticket Behaviour Variables

​Full .env.example Reference

Build docs developers (and LLMs) love

Required Variables

Whitelist Variables

General Bot Channel & Role Variables

Optional Variables

Redis Cache

HTTPS

Integrations

Monitoring Thresholds

Cache TTL Variables

API Variables

Ticket Behaviour Variables

Full `.env.example` Reference