Skip to main content
Docs

Getting Started

This guide will help you set up and run the Smutje Discord bot locally for development or production.

Prerequisites​

Before you begin, ensure you have:

  • Rust (2024 edition) - Install via rustup
  • Discord Bot Token - Create a bot at Discord Developer Portal
  • Heimdall API - Running instance with GraphQL, REST, and WebSocket endpoints
  • System API Key - Generated from Heimdall for bot authentication

Discord Bot Setup​

  1. Go to Discord Developer Portal

  2. Click "New Application" and give it a name

  3. Go to "Bot" section and click "Add Bot"

  4. Copy the Bot Token (keep this secret!)

  5. Enable these Privileged Gateway Intents:

    • PRESENCE INTENT (optional, for rich presence)
    • SERVER MEMBERS INTENT (required for member sync)
    • MESSAGE CONTENT INTENT (required for prefix commands)

  6. Go to "OAuth2" > "URL Generator":

    • Select scopes: bot, applications.commands
    • Select bot permissions: Administrator (or specific permissions)
    • Use the generated URL to invite the bot to your server

Environment Variables​

Create a .env file in platform/discord_bot/ or set these environment variables:

# Required
DISCORD_BOT_TOKEN=your_discord_bot_token
DISCORD_BOT_API_KEY=your_heimdall_api_key

# Optional (defaults shown)
DISCORD_BOT_API_GRAPHQL_ENDPOINT=http://localhost:3000/v1/gql
DISCORD_BOT_API_REST_ENDPOINT=http://localhost:3000/v1
DISCORD_BOT_API_WEBSOCKET_ENDPOINT=ws://localhost:3000/v1/ws
DISCORD_BOT_API_BIND_ADDRESS=0.0.0.0
DISCORD_BOT_API_BIND_PORT=3006
DISCORD_BOT_RUN_MODE=development
DISCORD_BOT_SENTRY_DSN=  # Optional: Sentry error tracking

Environment Variable Reference​

VariableRequiredDefaultDescription
DISCORD_BOT_TOKENYes-Discord bot token from Developer Portal
DISCORD_BOT_API_KEYYes-Heimdall system API key
DISCORD_BOT_API_GRAPHQL_ENDPOINTNohttp://localhost:3000/v1/gqlGraphQL endpoint URL
DISCORD_BOT_API_REST_ENDPOINTNohttp://localhost:3000/v1REST API endpoint URL
DISCORD_BOT_API_WEBSOCKET_ENDPOINTNows://localhost:3000/v1/wsWebSocket endpoint URL
DISCORD_BOT_API_BIND_ADDRESSNo0.0.0.0Health endpoint bind address
DISCORD_BOT_API_BIND_PORTNo3006Health endpoint port
DISCORD_BOT_RUN_MODENodevelopmentConfig mode: development or production
DISCORD_BOT_SENTRY_DSNNo-Sentry DSN for error tracking

Running the Bot​

The project uses just as a command runner:

# Build the bot
just build-dc-bot

# Run the bot
just run-dc-bot

# Run with auto-reload (watches for file changes)
just watch-dc-bot

# Run all checks (format, lint, build)
just verify-dc-bot

Using Cargo Directly​

# Navigate to the bot directory
cd platform/discord_bot

# Development mode
cargo run

# Production mode
DISCORD_BOT_RUN_MODE=production cargo run --release

# With specific log level
RUST_LOG=debug cargo run

Docker​

# Build stage
FROM rust:1.83 as builder
WORKDIR /app
COPY . .
RUN cargo build --release -p discord_bot

# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/discord_bot /usr/local/bin/
ENV DISCORD_BOT_RUN_MODE=production
CMD ["discord_bot"]

Verifying the Setup​

1. Check Bot Status​

Once the bot is running, you should see logs like:

INFO discord_bot::bot::client: Bot is ready!
INFO discord_bot::bot::client: Logged in as Smutje#1234
INFO discord_bot::clients::websocket: Connected to WebSocket

2. Test Commands​

In your Discord server, try these commands:

/ping        # Should respond with "Pong! 🏓"
/help        # Shows available commands
/info        # Shows bot information

3. Check Health Endpoint​

The bot exposes a health endpoint:

curl http://localhost:3006/health
# Returns: {"status":"healthy","uptime_seconds":123}

4. Verify WebSocket Connection​

Check the Heimdall API logs for WebSocket connection:

INFO heimdall_api::websocket: Client connected: discord_bot

Common Issues​

Bot Not Responding to Commands​

  1. Check intents: Ensure MESSAGE_CONTENT intent is enabled in Discord Developer Portal
  2. Check permissions: Bot needs permission to read/send messages in the channel
  3. Verify token: Make sure DISCORD_BOT_TOKEN is correct

WebSocket Connection Failed​

  1. Check endpoint: Verify DISCORD_BOT_API_WEBSOCKET_ENDPOINT is correct
  2. Check API key: Ensure DISCORD_BOT_API_KEY is valid
  3. Check Heimdall API: Ensure the API is running and WebSocket endpoint is available

Commands Not Syncing​

Slash commands need to be registered with Discord. This happens automatically on startup, but may take up to an hour to propagate globally. For faster testing:

  1. Use guild-specific commands (instant)
  2. Check for registration errors in logs

Permission Denied Errors​

  1. Link Discord account: User must link Discord to their Heimdall account
  2. Assign roles: User needs roles with required permissions
  3. Check RBAC: Verify permissions are seeded in Heimdall database

Just Commands Reference​

# Building
just build-dc-bot           # Build the Discord bot
just build-dc-bot-release   # Build in release mode

# Running
just run-dc-bot             # Run the Discord bot
just watch-dc-bot           # Run with auto-reload on file changes

# Code Quality
just check-dc-bot           # Check code without building
just lint-dc-bot            # Run clippy lints
just fmt-dc-bot             # Format Rust code
just verify-dc-bot          # Run all checks (format, lint, check)

# Testing
just test-dc-bot            # Run tests

# Protobuf
just proto                  # Force regenerate Protobuf code

Next Steps​