Quick Start¶

Get the API and bot running locally in minutes.

Prerequisites

This guide assumes you've completed the Installation steps.

Start Local Infrastructure¶

Start PostgreSQL and MinIO:

docker compose -f docker-compose.local.yml up -d

Verify all services are healthy:

docker compose -f docker-compose.local.yml ps

All services should show "Up (healthy)" status.

Running the API¶

Start the Litestar API server:

just run-api

This command: - Automatically loads .env.local - Runs litestar run with hot reload enabled - Serves on http://localhost:8000

Verify API is Running¶

Open your browser to:

API Docs: http://localhost:8000/schema
Health Check: http://localhost:8000/healthcheck

You should see the interactive OpenAPI documentation.

Running the Bot¶

Start the Discord bot:

just run-bot

This command: - Automatically loads .env.local - Runs the bot with your configured Discord token - Connects to the local API at localhost:8000

Verify Bot is Running¶

Check the terminal output for:

Logged in as YourBotName#1234
Bot is ready.

In your Discord server, the bot should appear online.

Testing the Integration¶

1. Trigger a Bot Command¶

In Discord, send a command to test the bot:

/map search parkour

2. Check API Logs¶

In the API terminal, you should see incoming requests from the bot.

3. Verify background work¶

Run just test-queue-fast for backend queue acceptance. Run just test-queue to include isolated process and database failure tests. The full suite does not connect to Discord or require live service credentials.

Development Workflow¶

Make Code Changes¶

The API runs with --reload, so changes are automatically picked up. For the bot, you'll need to restart the process (Ctrl+C and run just run-bot again).

Run Tests¶

Test the API:

just test-api

This runs pytest with 8 parallel workers.

Lint Code¶

Before committing, run linters:

just lint-all

This formats code with Ruff and type-checks with BasedPyright.

Common Tasks¶

View Logs¶

API logs: Displayed in the terminal where just run-api is running

Bot logs: Displayed in the terminal where just run-bot is running

Database logs:

docker compose -f docker-compose.local.yml logs -f postgres-local

MinIO logs:

docker compose -f docker-compose.local.yml logs -f minio-local

Stop Services¶

Stop infrastructure services:

docker compose -f docker-compose.local.yml down

Stop API/bot: Press Ctrl+C in their respective terminals.

Re-sync Dependencies¶

After pulling changes or switching branches:

just sync

Next Steps¶

Local Development Guide - Detailed local development documentation
Bot Architecture - Understand how the bot works
API Documentation - Learn about API endpoints
Contributing Guide - Make your first contribution

Troubleshooting¶

Port Already in Use¶

If port 8000 is already in use, find and kill the process:

lsof -ti:8000 | xargs kill -9

Bot Won't Connect¶

Verify DISCORD_TOKEN is set in .env.local
Check that the bot has proper permissions in your Discord server
Ensure intents are enabled in the Discord Developer Portal

Database Connection Failed¶

Verify Docker services are running:

docker compose -f docker-compose.local.yml ps

Check PostgreSQL logs:

docker compose -f docker-compose.local.yml logs postgres-local

Verify database credentials in .env.local:

POSTGRES_HOST=localhost
POSTGRES_USER=genji
POSTGRES_PASSWORD=local_dev_password
POSTGRES_DB=genjishimada

Queue Connection Failed¶

Check PostgreSQL health and apply the queue migration. Run just queue-credentials-local to set the queue-only login and update .env.local, then restart the bot. See Queue operations.

MinIO Connection Failed¶

Verify MinIO is healthy:

docker compose -f docker-compose.local.yml ps minio-local

Ensure bucket exists (see Installation Guide)