> ## Documentation Index
> Fetch the complete documentation index at: https://anniemei.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Use the hosted Annie Mei bot or self-host it with separate bot and auth services.

# Installation guide

This guide covers both ways to get Annie Mei running:

* Use the hosted bot in your Discord server
* Self-host Annie Mei from source

## Option 1: use the hosted bot

If you want the fastest setup, invite the hosted Annie Mei bot to your Discord server:

[Add Annie Mei to your Discord server](https://discord.com/oauth2/authorize?client_id=962106280430932079\&permissions=388160\&scope=bot)

After you add it, head to the [Quickstart Guide](/quickstart) to try the core slash commands.

<Note>
  You'll need permission to manage the Discord server before you can add bots.
</Note>

## Option 2: self-host Annie Mei

Use this path if you want to run your own instance, change the code, or develop new features.

Self-hosted Annie Mei now has two Rust services:

| Service                 | Purpose                                                       | Required for                      |
| ----------------------- | ------------------------------------------------------------- | --------------------------------- |
| `annie-mei` bot service | Discord slash commands, AniList and theme song lookups        | All bot features                  |
| `auth` service          | AniList OAuth start and callback flow, secure account linking | `/register` and new account links |

If you want full feature parity with the hosted bot, run both services.

<CardGroup cols={2}>
  <Card title="Self-hosting architecture" icon="boxes" href="/self-hosting/architecture">
    See how the bot service and auth service fit together.
  </Card>

  <Card title="Bot service" icon="bot" href="/self-hosting/bot-service">
    Configure and run the main Discord bot process.
  </Card>

  <Card title="Auth service" icon="shield-check" href="/self-hosting/auth-service">
    Configure and run the AniList OAuth companion service.
  </Card>

  <Card title="Environment Variables" icon="key" href="/deployment/environment-variables">
    Review the current env surface for both services.
  </Card>
</CardGroup>

## Prerequisites

Before you begin, ensure you have the following installed:

* **Rust 1.95 or higher** - Install from [rustup.rs](https://rustup.rs/)
* **PostgreSQL** - The bot and auth service both need database access
* **Redis** - The bot uses Redis for cached API responses
* **Git** - To clone the repository

<Note>
  Annie Mei uses the Rust 2024 edition. Make sure your Rust installation is up to date:

  ```bash theme={}
  rustup update
  ```
</Note>

## What you need to configure

Before you start the services, gather credentials for:

1. **Discord Bot Token** from the [Discord Developer Portal](https://discord.com/developers/applications)
2. **Spotify API credentials** from [Spotify for Developers](https://developer.spotify.com/)
3. **MyAnimeList API client ID** from [MyAnimeList API Config](https://myanimelist.net/apiconfig)
4. **AniList OAuth app credentials** for the auth service
5. **Sentry DSN** if you want production-style monitoring

Both services also need PostgreSQL access. The bot needs Redis. See [Environment Variables](/deployment/environment-variables) for the full reference.

<Warning>
  Never commit your `.env` file to version control. Add it to `.gitignore` to keep your credentials safe.
</Warning>

## Self-host checklist

<Steps>
  <Step title="Clone the repositories">
    ```bash theme={}
    git clone https://github.com/annie-mei/annie-mei.git
    git clone https://github.com/annie-mei/auth.git
    cd annie-mei
    ```
  </Step>

  <Step title="Prepare PostgreSQL and Redis">
    Create the database resources your deployment will use.

    ```bash theme={}
    createdb annie_mei
    ```

    <Note>
      Use the same PostgreSQL database for the bot and auth service. The auth service runs OAuth migrations on startup, and the bot runs its settings migrations on startup. The bot also needs Redis before `cargo run` succeeds.
    </Note>
  </Step>

  <Step title="Configure the bot service">
    Create the bot `.env` file in the repo root and set the current bot variables.

    ```bash theme={}
    touch .env
    ```

    <Note>
      The bot now requires `AUTH_SERVICE_BASE_URL` and `OAUTH_CONTEXT_SIGNING_SECRET` at startup. Use [Bot service](/self-hosting/bot-service) for the exact setup.
    </Note>
  </Step>

  <Step title="Configure the auth service">
    Set up the auth repo `.env`, your AniList OAuth app, and the shared OAuth secrets.

    ```bash theme={}
    cd ../auth
    cp .env.example .env
    ```

    Use [Auth service](/self-hosting/auth-service) for the exact setup.
  </Step>

  <Step title="Run both services">
    Start the auth service and the bot service in separate terminals.

    ```text theme={}
    terminal 1: cd ../auth && cargo run
    terminal 2: cd ../annie-mei && cargo run
    ```

    The local default is `http://127.0.0.1:8000` for the auth service. Use `http://127.0.0.1:8000/healthz` for liveness and `http://127.0.0.1:8000/readyz` for readiness.
  </Step>

  <Step title="Verify the stack">
    Test the core flows in Discord:

    ```text theme={}
    /ping
    /register
    /whoami
    ```

    `/register` should open the auth service flow in your browser, and `/whoami` should show the linked AniList account after the callback finishes.
  </Step>
</Steps>

## Where to go next

* Use [Self-hosting architecture](/self-hosting/architecture) to understand the service split
* Use [Bot service](/self-hosting/bot-service) for the main process setup
* Use [Auth service](/self-hosting/auth-service) for AniList OAuth setup
* Use [Environment Variables](/deployment/environment-variables) for the current config reference

## Next steps

Now that you have Annie Mei running, check out the [Quickstart Guide](/quickstart) to learn about all available commands and features.