Development Setup

Get Annie Mei running locally for development

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.94 or later - Install via rustup
• PostgreSQL - For database storage
• Redis - For caching API responses
• Diesel CLI (optional) - For creating or running migrations manually during development

Install Diesel CLI

cargo install diesel_cli --no-default-features --features postgres

Clone the Repository

1. Clone from GitHub

   git clone https://github.com/annie-mei/annie-mei.git
   cd annie-mei
   
2. 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

# Spotify API (for theme songs)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# MyAnimeList API
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

Get a Discord Bot Token

1. Go to Discord Developer Portal
2. Create a new application
3. Navigate to Bot section
4. Click Reset Token and copy the token
5. Copy the token into DISCORD_TOKEN

Get Spotify API Credentials

1. Go to Spotify Developer Dashboard
2. Create a new app
3. 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://[e-mail]/123456

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

Set up AniList OAuth linking

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

Database Setup

1. Create PostgreSQL Database

   createdb annie_mei
   

   Or using psql:

   CREATE DATABASE annie_mei;
   
2. Run Migrations

   Apply all database migrations using Diesel if you want to prepare the database before starting the bot:

   diesel migration run
   

   Annie Mei also runs embedded migrations automatically on startup, so this step is optional for a normal local run. See the Database guide for more details.

3. Verify Schema

   Check that src/schema.rs was generated:

   cat src/schema.rs
   

   Never manually edit src/schema.rs - it’s auto-generated by Diesel migrations.

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:

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

Verify Installation

Once the bot is running and invited:

1. Open Discord
2. Type /ping in a channel
3. 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