Skip to main content

Documentation Index

Fetch the complete documentation index at: https://anniemei.app/llms.txt

Use this file to discover all available pages before exploring further.

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
  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
  1. Go to Spotify Developer Dashboard
  2. Create a new app
  3. Copy the Client ID and Client Secret
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.
  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:
KeyJobWhat it does
cclippy-allRun Clippy on all targets
ddevRun and restart the bot on changes
rrun-longSame as dev, explicit alias
ppedanticRun 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

  • Check that DISCORD_TOKEN is correct
  • Check logs for connection errors: RUST_LOG=serenity=debug cargo run
  • 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
  • Verify PostgreSQL is running: pg_isready
  • Check DATABASE_URL format: postgresql://user:password@host/database
  • Ensure the database exists: psql -l | grep annie_mei
  • 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