Skip to main content

​
Quickstart Guide

This guide will help you get Template Worker up and running quickly. By the end, you’ll have a working worker pool that can execute templates and handle Discord events.
This quickstart assumes you have Rust, PostgreSQL, and basic familiarity with Discord bots. For production deployments, see the Deployment guides.

​
Prerequisites

Before you begin, ensure you have:
  • Rust (1.70 or later) - Install Rust
  • PostgreSQL (14 or later) - Running database instance
  • Discord Bot Token - From the Discord Developer Portal
  • Object Storage - S3-compatible storage or local filesystem
  • Sandwich Gateway (optional) - For production Discord gateway proxy
1
Clone and Build
2
First, clone the repository and build the project:
3
git clone https://github.com/Anti-Raid/template-worker.git
cd template-worker
cargo build --release
4
The first build will take several minutes as Cargo downloads and compiles dependencies.
5
Configure the Application
6
Create a config.yaml file in the project root:
7
discord_auth:
  token: "YOUR_BOT_TOKEN"
  client_id: "YOUR_CLIENT_ID"
  client_secret: "YOUR_CLIENT_SECRET"
  root_users:
    - "123456789012345678"  # Your Discord user ID
  allowed_redirects:
    - "http://localhost:3000"

meta:
  postgres_url: "postgresql://user:password@localhost/antiraid"
  proxy: "http://localhost:8080"  # Or your proxy URL
  support_server_invite: "https://discord.gg/your-invite"
  sandwich_http_api: "http://localhost:8000"  # Sandwich gateway API
  default_error_channel: "1234567890"  # Channel ID for error logs

object_storage:
  type: "local"  # Use "s3-like" for production
  base_path: "./data/storage"
  # For S3-compatible storage:
  # type: "s3-like"
  # endpoint: "s3.amazonaws.com"
  # access_key: "YOUR_ACCESS_KEY"
  # secret_key: "YOUR_SECRET_KEY"
  # secure: true
  # cdn_endpoint: "cdn.example.com"
  # cdn_secure: true

sites:
  api: "http://localhost:3030"
  frontend: "http://localhost:3000"
  docs: "https://docs.antiraid.xyz"

servers:
  main: "1234567890"  # Your main guild ID

addrs:
  template_worker: "0.0.0.0:3030"  # Public API address
  mesophyll_server: "127.0.0.1:0"  # Mesophyll coordination (random port)
8
Never commit your config.yaml file to version control. Add it to .gitignore immediately.
9
Set Up the Database
10
Run the database migrations to create the required schema:
11
cargo run --release -- --worker-type migrate
12
This will:
13
  • Connect to your PostgreSQL database
  • Create all required tables
  • Set up indexes and constraints
  • Prepare the database for worker operations
    • 14
    You should see output like:
    15
    (template_worker) INFO - Connecting to database
(migrations) INFO - Applying migration: tenantstate
(migrations) INFO - Applying migration: kv_generic
(migrations) INFO - All migrations applied successfully
    16
    Register Discord Commands
    17
    Register the bot’s slash commands with Discord:
    18
    cargo run --release -- --worker-type register
    19
    This reads the built-in command definitions and registers them globally with Discord’s API. Commands will be available within an hour (or instantly in your development guild).
    20
    You only need to run this when commands change. Discord caches command definitions.
    21
    Start the Worker Pool
    22
    Now you’re ready to start the actual worker system. Template Worker supports two main topologies:
    23
    Option 1: Thread Pool (Development)
    24
    For development and testing, use the thread-based worker pool:
    25
    cargo run --release -- --worker-type threadpool
    26
    This starts:
    27
  • A pool of WorkerThread instances
  • Each worker in its own thread
  • Communication via Tokio channels
  • Shared database connections
    • 28
    Advantages:
    29
  • Faster startup
  • Lower memory usage
  • Easier debugging
  • Single process to manage
    • 30
    Use when:
    31
  • Developing locally
  • Testing templates
  • Running in resource-constrained environments
    • 32
    Option 2: Process Pool (Production)
    33
    For production deployments, use the process-based worker pool:
    34
    cargo run --release -- --worker-type processpool --process-workers 4
    35
    This starts:
    36
  • A master process managing the pool
  • Multiple worker processes (one per shard)
  • Communication via Mesophyll (WebSocket)
  • True process isolation
    • 37
    Advantages:
    38
  • Better fault isolation
  • Independent worker crashes
  • Production-grade reliability
  • Scales to many workers
    • 39
    Use when:
    40
  • Running in production
  • Handling many guilds
  • Need maximum reliability
    • 41
    Set --process-workers to match your Discord shard count for optimal guild distribution.
    42
    Test the Shell (Optional)
    43
    Template Worker includes an interactive Fauxpas shell for testing Lua templates:
    44
    cargo run --release -- --worker-type shell
    45
    This launches a REPL where you can:
    46
  • Execute Luau code interactively
  • Test template functions
  • Debug worker behavior
  • Prototype new features
    • 47
    Example session:
    48
    fauxpas> print("Hello from Template Worker!")
Hello from Template Worker!

fauxpas> local result = 2 + 2
fauxpas> print(result)
4

fauxpas> -- Access built-in functions
fauxpas> local discord = require("@antiraid/discord")
fauxpas> print(discord.version)
    49
    The shell doesn’t provide full worker environment access yet, but it’s useful for testing Lua logic and debugging templates.

    ​
    Configuration Options

    Template Worker accepts several command-line arguments to customize behavior:

    ​
    Common Arguments

    --worker-type <TYPE>         # Worker mode: register, migrate, shell, threadpool, processpool
--max-db-connections <NUM>   # Database connection pool size (default: 7)
--worker-debug              # Enable debug logging for Luau VMs
--tokio-threads-master <NUM> # Tokio threads for master process (default: 10)
--tokio-threads-worker <NUM> # Tokio threads per worker (default: 3)
--use-tokio-console         # Enable tokio-console debugging

    ​
    Process Pool Specific

    --process-workers <NUM>  # Number of worker processes to spawn
--worker-id <ID>        # Worker ID (only for processpoolworker mode)

    ​
    Example Configurations

    Development setup: 
    cargo run --release -- \
  --worker-type threadpool \
  --max-db-connections 3 \
  --worker-debug
    Production setup: 
    cargo run --release -- \
  --worker-type processpool \
  --process-workers 16 \
  --max-db-connections 10 \
  --tokio-threads-master 20 \
  --tokio-threads-worker 5
    Debug with tokio-console: 
    cargo run --release -- \
  --worker-type threadpool \
  --use-tokio-console

    ​
    Verify the Installation

    Once your worker is running, verify everything works:

    ​
    Check the API

    The worker exposes an HTTP API (default port 3030): 
    curl http://localhost:3030/health
    You should receive a health check response.

    ​
    View OpenAPI Documentation

    Template Worker includes interactive API documentation at: 
    http://localhost:3030/swagger-ui/
    This shows all available endpoints with:
    • Request/response schemas
    • Authentication requirements
    • Example payloads
    • Try-it-out functionality

    ​
    Check Logs

    The worker logs important events to stdout: 
    (template_worker) INFO - Proxy URL: http://localhost:8080
(template_worker) INFO - HttpBuilder done
(template_worker) INFO - Connecting to database
(template_worker) INFO - Current user: AntiRaid (1234567890)
(template_worker) INFO - Starting RPC server
(template_worker) INFO - Starting using autosharding
    Worker processes log with [Worker N] prefixes to distinguish output from different workers.

    ​
    Understanding Worker Modes

    Template Worker supports six different operational modes: 
    # Register Discord slash commands
cargo run -- --worker-type register

    ​
    Next Steps

    Now that you have Template Worker running, explore:

    Architecture Overview

    Learn how the worker system is designed

    Worker System Deep Dive

    Understand WorkerLike, pools, and topologies

    Configuration Guide

    Complete configuration reference

    API Reference

    Explore the HTTP and WebSocket APIs

    ​
    Troubleshooting

    ​
    Database Connection Errors

    If you see connection errors:
    1. Verify PostgreSQL is running: psql -U user -d antiraid
    2. Check the connection string in config.yaml
    3. Ensure the database exists: createdb antiraid
    4. Verify network access if using remote database

    ​
    Discord Authentication Errors

    If the bot can’t authenticate:
    1. Verify your bot token is correct
    2. Check that the bot has required intents enabled
    3. Ensure the client ID matches your application
    4. Confirm the bot is added to at least one guild

    ​
    Compilation Errors

    If the build fails:
    1. Update Rust: rustup update
    2. Clean build artifacts: cargo clean
    3. Check Cargo.toml dependencies are accessible
    4. Ensure you have required system libraries

    ​
    Worker Startup Issues

    If workers fail to start:
    1. Check logs for specific error messages
    2. Verify all config.yaml fields are filled
    3. Ensure ports are not already in use
    4. Check file permissions for object storage path
    For process pool mode, ensure your system allows enough open file descriptors. Use ulimit -n 65535 on Linux/macOS.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us