Development Setup

This guide walks you through setting up Annie Mei for local development.

This page focuses on the main bot service. If you want to test /register end to end, also set up the Auth service.

Prerequisites

Ensure you have the following installed:

Rust 1.95 or later - Install via rustup
PostgreSQL - For database storage
Redis - For caching API responses
SQLx CLI (optional) - For auth service schema work

Install SQLx CLI

cargo install sqlx-cli --no-default-features --features postgres

Clone the Repository

Clone from GitHub

git clone https://github.com/annie-mei/annie-mei.git
cd annie-mei

Install Dependencies

Rust dependencies are managed via Cargo.toml. Download and compile all dependencies:

cargo build

This will take a few minutes on first run as it compiles all dependencies.

Configuration

Environment Variables

Create a .env file in the project root with the following variables:

# Discord Bot Configuration
DISCORD_TOKEN=your_discord_bot_token

# Database
DATABASE_URL=postgresql://username:password@localhost/annie_mei

# Cache
REDIS_URL=redis://127.0.0.1:6379

# Error Tracking
SENTRY_DSN=your_sentry_dsn
SENTRY_TRACES_SAMPLE_RATE=0.1
ENV=development

# External APIs
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
MAL_CLIENT_ID=your_mal_client_id

# Privacy
USERID_HASH_SALT=generate_a_random_secret_value

# OAuth linking
AUTH_SERVICE_BASE_URL=https://auth.your-domain.com
OAUTH_CONTEXT_SIGNING_SECRET=generate_a_random_secret_value
OAUTH_CONTEXT_TTL_SECONDS=300

# LLM (optional — enables /search natural-language queries)
# GEMINI_API_KEY=
# LLM_MODEL=gemini-3.1-flash-lite
# LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai

Get a Discord Bot Token

Go to Discord Developer Portal
Create a new application
Navigate to Bot section
Click Reset Token and copy the token
Copy the token into DISCORD_TOKEN

Get Spotify API Credentials

Go to Spotify Developer Dashboard
Create a new app
Copy the Client ID and Client Secret

Set up Sentry DSN

The current app startup expects SENTRY_DSN to be set. For local development, you can use a dummy DSN:

SENTRY_DSN=https://[email protected]/123456

For production, sign up at sentry.io and create a Rust project.

Set up AniList OAuth linking

Set up the Auth service
Use the same value for OAUTH_CONTEXT_SIGNING_SECRET in both services
Set AUTH_SERVICE_BASE_URL to the auth service origin, for example https://auth.example.com
Start the bot after both services are configured and reachable

Database Setup

Create PostgreSQL Database

createdb annie_mei

Or using psql:

CREATE DATABASE annie_mei;

Run Migrations

The bot runs its own SQLx migrations at startup for settings tables. If you are testing /register, run the auth service once to apply its OAuth SQLx migrations to the shared database.

cd ../auth
cargo run

This step is optional for a bot-only local run. See the Database guide for more details.

Verify Schema

Check that the expected tables exist:

psql $DATABASE_URL -c "\dt"

Redis Setup

Start a local Redis instance:

# Using Homebrew (macOS)
brew services start redis

# Using Docker
docker run -d -p 6379:6379 redis:latest

# Using apt (Ubuntu/Debian)
sudo systemctl start redis-server

Verify Redis is running:

redis-cli ping
# Should return: PONG

Running Locally

Development Mode

The repo includes a bacon.toml configuration. Install bacon once:

cargo install bacon

Then run the bot with auto-restart on code changes:

bacon

This runs the dev job by default, which executes cargo run and restarts the bot whenever a source file changes. Other useful jobs:

Key	Job	What it does
`c`	`clippy-all`	Run Clippy on all targets
`d`	`dev`	Run and restart the bot on changes
`r`	`run-long`	Same as dev, explicit alias
`p`	`pedantic`	Run Clippy in pedantic mode

You can also run a specific job directly:

bacon clippy-all
bacon test
bacon nextest   # requires cargo-nextest

To run the bot without bacon:

cargo run

To enable detailed tracing:

RUST_LOG=debug cargo run

Filter logs to specific modules:

RUST_LOG=annie_mei=debug,serenity=warn cargo run

Fast Type Checking

For quick feedback without running the bot:

cargo check

This is much faster than cargo build and catches most errors.

Production Build

Compile an optimized release binary:

cargo build --release

The binary will be at target/release/annie-mei.

Invite Bot to Test Server

Generate an OAuth2 invite link:

Go to your app in Discord Developer Portal
Navigate to OAuth2 → URL Generator
Select scopes:
- bot
- applications.commands
Select bot permissions:
- Send Messages
- Embed Links
- Read Message History
Copy the generated URL and open it in your browser
Select your test server and authorize

Verify Installation

Once the bot is running and invited:

Open Discord
Type /ping in a channel
The bot should respond with a greeting

If you see the response, your development environment is ready!

Troubleshooting

Bot doesn't show online

Check that DISCORD_TOKEN is correct
Check logs for connection errors: RUST_LOG=serenity=debug cargo run

Slash commands not appearing

Commands are registered globally and can take up to 1 hour to propagate
For faster development, use guild-specific commands (requires code changes)
Check logs for command registration errors

Database connection errors

Verify PostgreSQL is running: pg_isready
Check DATABASE_URL format: postgresql://user:password@host/database
Ensure the database exists: psql -l | grep annie_mei

Redis connection errors

Verify Redis is running: redis-cli ping
Check REDIS_URL format: redis://127.0.0.1:6379
For password-protected Redis: redis://:password@host:port

Next Steps

Architecture

Understand the project structure and technology stack

Adding Commands

Create your first slash command

Database

Learn database migration workflows

Testing

Run tests and ensure code quality

Getting Started

Self-hosting

Commands

Legal

Development

Deployment

API Reference

Prerequisites

Install SQLx CLI

Clone the Repository

Configuration

Environment Variables

Database Setup

Redis Setup

Running Locally

Development Mode

Fast Type Checking

Production Build

Invite Bot to Test Server

Verify Installation

Troubleshooting

Next Steps

Architecture

Adding Commands

Database

Testing

​Prerequisites

​Install SQLx CLI

​Clone the Repository

​Configuration

​Environment Variables

​Database Setup

​Redis Setup

​Running Locally

​Development Mode

​Fast Type Checking

​Production Build

​Invite Bot to Test Server

​Verify Installation

​Troubleshooting

​Next Steps

Architecture

Adding Commands

Database

Testing

Prerequisites

Install SQLx CLI

Clone the Repository

Configuration

Environment Variables

Database Setup

Redis Setup

Running Locally

Development Mode

Fast Type Checking

Production Build

Invite Bot to Test Server

Verify Installation

Troubleshooting

Next Steps