Merge branch 'main' into main

Author: KNTSoul

.dockerignore

@@ -0,0 +1,16 @@
+node_modules
+npm-debug.log*
+.env
+.env.*
+!.env.example
+.git
+.github
+.cursor
+tests
+backups
+logs
+*.md
+!README.md
+.DS_Store
+coverage
+.agent-tools

.env.example

@@ -3,13 +3,10 @@
 # Discord Bot Configuration
 DISCORD_TOKEN=your_discord_bot_token_here
 CLIENT_ID=your_discord_client_id_here
+# Your server ID (used in the setup tutorial; slash commands register globally via CLIENT_ID).
 GUILD_ID=your_discord_guild_id_here
 OWNER_IDS=your_discord_id_here (optional)
 
-# Optional — enable slash commands in every server the bot is invited to.
-# Leave unset or false for single-server setup (recommended for most users).
-MULTI_GUILD=false
-
 # Bot Runtime Configuration
 NODE_ENV=production
 LOG_LEVEL=warn
@@ -54,16 +51,18 @@ BACKUP_DIR=./backups
 BACKUP_RETENTION_DAYS=14
 POSTGRES_RESTORE_URL=
 
-# Music (Lavalink + Riffy) — requires a Lavalink v4 server
-# Local dev: run Lavalink via docker compose (see README), then use localhost below.
-# Docker Compose bot service uses LAVALINK_HOST=lavalink instead.
-LAVALINK_HOST=localhost
-LAVALINK_PORT=2333
-LAVALINK_PASSWORD=youshallnotpass
-LAVALINK_SECURE=false
-LAVALINK_NAME=Main
-# Optional: override nodes as JSON array (for multiple Lavalink nodes)
+# Music (Lavalink + Riffy) — requires Lavalink v4 nodes
+# Default: loads public v4 SSL nodes from lavalink/nodes.json
+# Source: https://lavalink.darrennathanael.com/SSL/Lavalink-SSL/
+# LAVALINK_NODES_FILE=lavalink/nodes.json
+# Optional: override nodes as JSON array (takes priority over nodes file)
 # LAVALINK_NODES=[{"host":"lavalink","port":2333,"password":"youshallnotpass","secure":false,"name":"Main"}]
+# Self-hosted single node fallback (used only if nodes file/env array are absent):
+# LAVALINK_HOST=localhost
+# LAVALINK_PORT=2333
+# LAVALINK_PASSWORD=youshallnotpass
+# LAVALINK_SECURE=false
+# LAVALINK_NAME=Main
 LAVALINK_SEARCH_PLATFORM=ytmsearch
 LAVALINK_REST_VERSION=v4
 

.github/workflows/tests.yml

@@ -7,15 +7,14 @@ Thank you for your interest in contributing to TitanBot! This guide covers local
 - Bug fixes and reliability improvements
 - New commands or enhancements to existing features
 - Documentation updates
-- Test coverage for behavior that is easy to regress
 
 Before starting large features, open an issue or discuss in the [support server](https://discord.gg/8kJBYhTGW9) so we can align on scope and avoid duplicate work.
 
 ## Getting Started
 
 ### Prerequisites
 
-- **Node.js 18+** (CI uses Node 20)
+- **Node.js 20+** (Docker and CI use Node 20)
 - **PostgreSQL** (recommended for development; the bot can fall back to in-memory storage if PostgreSQL is unavailable)
 - A **Discord bot application** with the intents listed in [README.md](README.md#required-bot-intents)
 
@@ -46,31 +45,14 @@ For Docker-based setup, see [README.md](README.md#docker-deployment-recommended)
 
 1. **Fork the repository** and create a branch from `main`.
 2. **Make focused changes** — one logical change per pull request when possible.
-3. **Run tests** before opening a PR (see below).
-4. **Open a pull request** with a clear description of what changed and why.
+3. **Open a pull request** with a clear description of what changed and why.
 
 Use descriptive branch names, for example:
 
 - `fix/ticket-panel-refresh`
 - `feat/economy-shop-filter`
 - `docs/contributing-guide`
 
-## Running Tests
-
-Tests use Node's built-in test runner:
-
-```bash
-npm test
-```
-
-Test files live in `tests/` and follow the `*.test.js` naming pattern. When adding or changing behavior, add or update tests for:
-
-- Permission checks and command access rules
-- Parsing, validation, and utility logic
-- UI/panel builders and status helpers
-
-CI runs `npm test` on every pull request and on pushes to `main` and `master`. A separate workflow also validates database migrations against PostgreSQL when migration-related code changes.
-
 ## Database & Migrations
 
 TitanBot uses PostgreSQL as its primary store. If PostgreSQL is unreachable at startup, the bot can operate in a **degraded in-memory mode** — but that mode is not suitable for production and should not be the only way you test persistence-related changes.
@@ -91,7 +73,7 @@ Test features that read or write guild data with **both** PostgreSQL and the mem
 
 - **Match existing style** — ES modules (`import`/`export`), async/await, and the conventions used in neighboring files.
 - **Handle errors gracefully** — catch failures, log with context, and send user-friendly embed replies where appropriate.
-- **Avoid breaking guild isolation** — guild-specific config and data must stay scoped per server, especially when `MULTI_GUILD=true`.
+- **Avoid breaking guild isolation** — guild-specific config and data must stay scoped per server (`guild:{guildId}:...` keys, `interaction.guildId`).
 - **Keep changes minimal** — prefer extending existing utilities and services over duplicating logic.
 - **Document user-facing behavior** — update README.md when setup steps or configuration change; mention new env vars in `.env.example`.
 

CONTRIBUTING.md

@@ -1,20 +1,14 @@
 FROM node:20-alpine
 
-# Create app directory
 WORKDIR /usr/src/app
 
-# Install app dependencies
-# A wildcard is used to ensure both package.json AND package-lock.json are copied
-COPY package*.json ./
+ENV NODE_ENV=production
 
-# Install only production dependencies
+COPY package*.json ./
 RUN npm ci --omit=dev
 
-# Bundle app source
 COPY . .
 
-# Expose the health check port from src/app.js
 EXPOSE 3000
 
-# Start the bot
-CMD [ "npm", "start" ]
+CMD ["npm", "start"]

Dockerfile

@@ -109,28 +109,38 @@ TitanBot is fully containerized for easy deployment.
    ```
 
 2. **Configure environment variables:**
-   Create a `.env` file from `.env.example` and fill in your bot details and PostgreSQL credentials.
+   ```bash
+   cp .env.example .env
+   ```
+   Set at minimum `DISCORD_TOKEN`, `CLIENT_ID`, and `GUILD_ID`. Docker Compose also reads `POSTGRES_USER`, `POSTGRES_PASSWORD`, and `POSTGRES_DB` from `.env` (defaults: `titanbot` / `password` / `titanbot`).
 
-3. **Start the containers:**
+3. **Build and start the containers:**
    ```bash
-   docker-compose up -d
+   docker compose up -d --build
    ```
 
-This will start the bot, PostgreSQL, and Lavalink (when music is enabled).
+4. **Check status:**
+   ```bash
+   docker compose ps
+   curl http://localhost:3000/health
+   ```
+
+This starts the bot and PostgreSQL. The compose file sets `POSTGRES_SSL=false` and `AUTO_MIGRATE=true` for the bundled database. Music uses public Lavalink v4 nodes from `lavalink/nodes.json` by default.
 
 ### Music
 
 Music uses [Lavalink v4](https://github.com/lavalink-devs/Lavalink) via [Riffy](https://github.com/riffy-rb/riffy), similar to [Musicify](https://github.com/codebymitch/Musicify).
 
-1. Set in `.env`:
+1. By default, the bot loads multiple public v4 SSL nodes from [`lavalink/nodes.json`](lavalink/nodes.json) (sourced from [lavalink.darrennathanael.com](https://lavalink.darrennathanael.com/SSL/Lavalink-SSL/)). Edit that file to add or remove nodes.
+2. To self-host Lavalink instead, run `docker compose --profile local-lavalink up -d` and set single-node env vars in `.env`:
    ```env
    LAVALINK_HOST=lavalink
    LAVALINK_PORT=2333
    LAVALINK_PASSWORD=youshallnotpass
    LAVALINK_SECURE=false
    ```
-2. With Docker Compose, Lavalink is included automatically when you `docker compose up`.
-3. On Railway, deploy Lavalink separately or as another service and point `LAVALINK_HOST` at the private hostname.
+   Remove or rename `lavalink/nodes.json` so the bot falls back to those env vars.
+3. Override nodes inline with `LAVALINK_NODES` (JSON array) or point at another file with `LAVALINK_NODES_FILE`.
 4. Use `/play <song>` from a voice channel, or `/join` to connect without playing. Prefix shortcuts: `join`, `np`, `leave`, `pause`, `resume`, `skip`, `stop`, `volume <0-100>`, or `music <subcommand>`. Use `/nowplaying` and `/queue` for status; `/music` for loop, shuffle, seek, and other controls.
 
 ### Using GitHub Container Registry
@@ -145,7 +155,7 @@ docker pull ghcr.io/codebymitch/titanbot:main
 ## Manual Installation Steps
 
 ### Prerequisites
-- Node.js 18.0.0 or higher
+- Node.js 20.10.0 or higher
 - PostgreSQL server (recommended) or memory storage fallback
 - Discord bot application with proper intents
 
@@ -202,18 +212,13 @@ docker pull ghcr.io/codebymitch/titanbot:main
    This gives clear startup/online status messages while keeping logs simple for non-technical operators.
    If port `3000` is busy, the bot tries the next available ports automatically (up to `PORT_RETRY_ATTEMPTS`).
 
-### Running in multiple servers (optional)
-
-Most users run TitanBot on a **single server** with `GUILD_ID` set (default tutorial setup). If you want commands to work in **every server** the bot is invited to, opt in with:
+### Multiple servers
 
-```env
-MULTI_GUILD=true
-```
+Slash commands are registered **globally** on startup (via `CLIENT_ID`), so the bot works in every server it is invited to. `GUILD_ID` stays in the tutorial `.env` for setup steps but is not used for command registration.
 
-Notes for multi-server mode:
-- `GUILD_ID` is not used for command registration when `MULTI_GUILD=true` (you can leave it set or remove it)
+Notes:
 - Global slash commands may take up to about an hour to propagate on first deploy
-- Each server still has **isolated** config, economy, tickets, leveling, and other data
+- Each server has **isolated** data: config, economy, tickets, leveling, dashboards, warnings, etc. (all keys are scoped as `guild:{guildId}:...`)
 - In the [Discord Developer Portal](https://discord.com/developers/applications), ensure your bot is not restricted to a single guild if you plan to invite it elsewhere
 - Generate an OAuth2 invite URL from the [Discord Developer Portal](https://discord.com/developers/applications) (OAuth2 → URL Generator, scopes: `bot` and `applications.commands`)
 
@@ -235,6 +240,12 @@ Notes for multi-server mode:
    ```bash
    npm start
    ```
+
+> **Note on database migrations:** Schema tables and legacy key migrations run
+> **automatically on startup**, so` managed hosts like **Railway** need no manual
+> migration step — just deploy/restart. To disable auto-migration set
+> `AUTO_MIGRATE=false`. You can still run a manual key migration locally with
+> `node scripts/migrate-keys.js --dry-run` (preview) or `node scripts/migrate-keys.js`.
 <a name="bot-intents"></a>
 
 ## Required Bot Intents

README.md

@@ -3,27 +3,43 @@ services:
     build: .
     container_name: titanbot
     restart: unless-stopped
+    env_file:
+      - .env
     environment:
       - NODE_ENV=production
       - DISCORD_TOKEN=${DISCORD_TOKEN}
       - CLIENT_ID=${CLIENT_ID}
       - GUILD_ID=${GUILD_ID}
-      - MULTI_GUILD=${MULTI_GUILD:-false}
-      - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
-      - LAVALINK_HOST=lavalink
-      - LAVALINK_PORT=2333
-      - LAVALINK_PASSWORD=${LAVALINK_PASSWORD:-youshallnotpass}
-      - LAVALINK_SECURE=false
+      - DATABASE_URL=postgres://${POSTGRES_USER:-titanbot}:${POSTGRES_PASSWORD:-password}@db:5432/${POSTGRES_DB:-titanbot}
+      - POSTGRES_URL=postgres://${POSTGRES_USER:-titanbot}:${POSTGRES_PASSWORD:-password}@db:5432/${POSTGRES_DB:-titanbot}
+      - POSTGRES_HOST=db
+      - POSTGRES_PORT=5432
+      - POSTGRES_DB=${POSTGRES_DB:-titanbot}
+      - POSTGRES_USER=${POSTGRES_USER:-titanbot}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-password}
+      - POSTGRES_SSL=false
+      - AUTO_MIGRATE=true
+      - LOG_LEVEL=${LOG_LEVEL:-warn}
+      - LAVALINK_NODES_FILE=lavalink/nodes.json
       - PORT=3000
+      - WEB_HOST=0.0.0.0
+    ports:
+      - "${PORT:-3000}:3000"
     depends_on:
       db:
         condition: service_healthy
-      lavalink:
-        condition: service_started
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 40s
     networks:
       - titan-network
 
   lavalink:
+    profiles:
+      - local-lavalink
     image: ghcr.io/lavalink-devs/lavalink:4
     container_name: titanbot-lavalink
     restart: unless-stopped

docker-compose.yml

@@ -0,0 +1,30 @@
+[
+  {
+    "host": "lavalinkv4.serenetia.com",
+    "port": 443,
+    "password": "https://seretia.link/discord",
+    "secure": true,
+    "name": "Serenetia"
+  },
+  {
+    "host": "lavalink.jirayu.net",
+    "port": 443,
+    "password": "youshallnotpass",
+    "secure": true,
+    "name": "Jirayu"
+  },
+  {
+    "host": "lava-v4.millohost.my.id",
+    "port": 443,
+    "password": "https://discord.gg/mjS5J2K3ep",
+    "secure": true,
+    "name": "MilloHost"
+  },
+  {
+    "host": "lavalink-v4.triniumhost.com",
+    "port": 443,
+    "password": "free",
+    "secure": true,
+    "name": "TriniumHost"
+  }
+]