Installation

Prerequisites

Before installing Jill Stingray, ensure you have:

Discord Bot Token

Create a bot application at Discord Developer Portal

PostgreSQL Database

A PostgreSQL instance (local or cloud-hosted)

Node.js 24+

Required for npm installation method

Docker (Optional)

Recommended for production deployments

Creating a Discord Bot

Create Application

Navigate to the Discord Developer Portal and click New Application.Give your bot a name (e.g., “Jill Stingray”) and accept the terms.

Enable Bot User

Go to the Bot section in the left sidebar and click Add Bot.Copy the bot token and save it securely - you’ll need this for the DISCORD_TOKEN environment variable.

Configure Intents

In the Bot section, scroll down to Privileged Gateway Intents and enable:

Server Members Intent
Message Content Intent

These are required for member caching and command prefix detection.

Generate Invite Link

Go to OAuth2 → URL Generator and select:Scopes:

bot
applications.commands

Bot Permissions:

Manage Roles
Manage Channels
Read Messages/View Channels
Send Messages
Manage Messages
Embed Links
Attach Files
Read Message History
Add Reactions
Use Slash Commands

Copy the generated URL and use it to invite the bot to your server.

Installation Methods

Docker (Recommended)
npm/Node.js

Docker provides the easiest and most reliable deployment method.

Step 1: Clone Repository

git clone https://github.com/ItsTrudeauver/jill-stingray-pre.git
cd jill-stingray-pre

Step 2: Configure Environment

Create a .env file in the project root:

.env

DISCORD_TOKEN=your_discord_bot_token
DATABASE_URL=postgresql://user:password@host:5432/database
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_KEY=your_supabase_service_key
MAPILLARY_TOKEN=your_mapillary_token
GROQ_API_KEY=your_groq_api_key
BOT_OWNER_ID=your_discord_user_id
PORT=8080

See Configuration for detailed information about each environment variable.

Step 3: Build and Run

Build the Docker image:

docker build -t jill-stingray .

Run the container:

docker run -d \
  --name jill-stingray \
  --env-file .env \
  -p 8080:8080 \
  --restart unless-stopped \
  jill-stingray

Step 4: Verify Deployment

Check container logs:

docker logs -f jill-stingray

You should see:

--- Jill Stingray Boot Sequence ---
[DB] PostgreSQL Connected & Synced.
[CMD] Loaded /mix
[CMD] Loaded /geo
[EVT] Loaded event: ready
Jill Stingray is online. (User: YourBotName)
Mixing drinks and changing lives.
✅ Synced 25 Global Commands.

The bot exposes a health check endpoint at http://localhost:8080 that returns “Jill Stingray is mixing drinks…” when running.

Install and run Jill Stingray directly with npm.

Step 1: Clone Repository

git clone https://github.com/ItsTrudeauver/jill-stingray-pre.git
cd jill-stingray-pre

Step 2: Install Dependencies

The bot requires Node.js 24 or higher:

npm install

Key dependencies that will be installed:

package.json

{
  "dependencies": {
    "eris": "^0.17.2",
    "@supabase/supabase-js": "^2.90.0",
    "pg": "^8.16.3",
    "@napi-rs/canvas": "^0.1.88",
    "axios": "^1.13.2",
    "groq-sdk": "^0.37.0",
    "dotenv": "^16.6.1"
  }
}

@napi-rs/canvas requires system dependencies. On Alpine/Debian systems:

# Debian/Ubuntu
apt-get install -y python3 make g++ cairo-dev pango-dev \
  giflib-dev jpeg-dev librsvg-dev fontconfig

# Alpine
apk add --no-cache python3 make g++ cairo-dev pango-dev \
  giflib-dev jpeg-dev librsvg-dev fontconfig

Step 3: Configure Environment

Create a .env file:

.env

DISCORD_TOKEN=your_discord_bot_token
DATABASE_URL=postgresql://user:password@host:5432/database
SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_KEY=your_supabase_service_key
MAPILLARY_TOKEN=your_mapillary_token
GROQ_API_KEY=your_groq_api_key
BOT_OWNER_ID=your_discord_user_id
PORT=8080

Step 4: Start the Bot

npm start

Or use a process manager like PM2:

npm install -g pm2
pm2 start index.js --name jill-stingray
pm2 save
pm2 startup

Step 5: Verify Installation

Check the console output for:

--- Jill Stingray Boot Sequence ---
[Loader] Successfully loaded 25 VA-11 HALL-A drinks.
[DB] PostgreSQL Connected & Synced.
[CMD] Loaded /mix
[EVT] Loaded event: ready
Jill Stingray is online.

Database Setup

Jill Stingray automatically creates all required tables on first startup:

index.js (Lines 87-93)

await init();

loadCommands();
loadEvents();

bot.connect();

The init() function from /utils/db.js creates these tables:

guild_settings - Server configuration and admin roles
activity - User activity tracking for regulars
drinks - Drink order history and statistics
custom_roles - User-created custom roles
active_mutes - Timed mute management
triggers - Custom keyword triggers
emojis - Emoji usage statistics
dangeru_posts - Anonymous posting system
aliases - Username change history

No manual database setup required. The bot handles schema creation automatically.

Verifying Installation

Check Bot Online Status

The bot should appear online in your Discord server with the status:

Playing: VA-11 HALL-A OST
Or: Time to mix drinks and change lives.

Status rotates every 30 seconds.

Test Slash Commands

Type / in any channel and verify that Jill Stingray’s commands appear:

/help - Command menu
/mix - Mix drinks
/ping - Connection test

Test Basic Command

Run /ping to verify the bot is responding:

🏓 Pong! Latency: 45ms

Check Logs

Verify all commands and events loaded successfully:

docker logs jill-stingray
# or
pm2 logs jill-stingray

Look for:

[CMD] Loaded /commandname for each command
[EVT] Loaded event: eventname for each event
✅ Synced X Global Commands

Troubleshooting

Bot appears offline

Check Discord Token:

# Verify token is set correctly
echo $DISCORD_TOKEN

Check Logs:

docker logs jill-stingray

Common errors:

Error: Incorrect login credentials - Invalid bot token
Error: 401 Unauthorized - Token format error

Database connection fails

Verify Connection String:

// Format: postgresql://user:password@host:port/database
DATABASE_URL=postgresql://user:pass@localhost:5432/jillbot

Test Connection:

psql $DATABASE_URL -c "SELECT version();"

The bot requires ssl: { rejectUnauthorized: false } for cloud databases.

Slash commands don't appear

Wait for Sync: Global commands can take up to 1 hour to propagate. Use guild commands for instant updates:

events/ready.js (Lines 62-63)

await bot.bulkEditGuildCommands(TEST_GUILD_ID, commandData);

Check Permissions: Ensure the bot invite included applications.commands scope.

Canvas/Image errors

Install System Dependencies:Canvas requires native libraries:

# Alpine
apk add cairo-dev pango-dev jpeg-dev giflib-dev

# Debian/Ubuntu  
apt-get install libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev

Rebuild after installing dependencies:

npm rebuild @napi-rs/canvas

Next Steps

Configuration

Configure environment variables and API integrations

Server Setup

Set up admin roles and configure server-specific settings

Commands

Browse the complete command reference

Features

Explore drink mixing, Geoguessr, and more

Get Started

Features

Guides

Prerequisites

Discord Bot Token

PostgreSQL Database

Node.js 24+

Docker (Optional)

Creating a Discord Bot

Installation Methods

Step 1: Clone Repository

Step 2: Configure Environment

Step 3: Build and Run

Step 4: Verify Deployment

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Configure Environment

Step 4: Start the Bot

Step 5: Verify Installation

Database Setup

Verifying Installation

Troubleshooting

Next Steps

Configuration

Server Setup

Commands

Features

Build docs developers (and LLMs) love

Get Started

Features

Guides

​Prerequisites

Discord Bot Token

PostgreSQL Database

Node.js 24+

Docker (Optional)

​Creating a Discord Bot

​Installation Methods

​Step 1: Clone Repository

​Step 2: Configure Environment

​Step 3: Build and Run

​Step 4: Verify Deployment

​Step 1: Clone Repository

​Step 2: Install Dependencies

​Step 3: Configure Environment

​Step 4: Start the Bot

​Step 5: Verify Installation

​Database Setup

​Verifying Installation

​Troubleshooting

​Next Steps

Configuration

Server Setup

Commands

Features

Build docs developers (and LLMs) love

Prerequisites

Creating a Discord Bot

Installation Methods

Step 1: Clone Repository

Step 2: Configure Environment

Step 3: Build and Run

Step 4: Verify Deployment

Step 1: Clone Repository

Step 2: Install Dependencies

Step 3: Configure Environment

Step 4: Start the Bot

Step 5: Verify Installation

Database Setup

Verifying Installation

Troubleshooting

Next Steps