First Run Guide¶

This guide walks you through verifying your installation, creating the admin user, and testing the main features.

Verification Checklist¶

Before diving deeper, verify everything is working.

1. Check Services¶

docker compose ps

pg_isready -h localhost -p 5432
redis-cli ping  # should print PONG

2. Test API Documentation¶

Open these in a browser:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

3. Health Check¶

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy"
}

4. Database Tables¶

Check that tables were created:

docker compose exec db psql -U postgres -d postgres -c "\dt"

psql -h localhost -U postgres -d postgres -c "\dt"

You should see tables like user, tiers, rate_limits, api_keys, key_usage, key_permissions.

Initial Setup¶

Create the first admin user and the default tier.

Create Admin User and Default Tier¶

The admin credentials come from ADMIN_NAME, ADMIN_EMAIL, ADMIN_USERNAME, and ADMIN_PASSWORD in backend/.env.

docker compose exec web python -m scripts.setup_initial_data

cd backend
uv run python -m scripts.setup_initial_data

This creates:

• A default tier (used as the fallback for new users)
• The admin user (with is_superuser=true)

Testing Core Features¶

Authentication Flow (Sessions)¶

This boilerplate uses server-side sessions with HTTP-only cookies — no JWT.

1. Log In¶

curl -X POST "http://localhost:8000/api/v1/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=your_admin_password" \
  -c cookies.txt

Response sets an HTTP-only session_id cookie and returns a CSRF token:

{ "csrf_token": "..." }

cookies.txt now holds your session — pass it back with -b cookies.txt on subsequent requests.

2. Get the Current User¶

curl http://localhost:8000/api/v1/users/me -b cookies.txt

3. Create a New User¶

curl -X POST "http://localhost:8000/api/v1/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "username": "johndoe",
    "email": "john@example.com",
    "password": "securepassword123"
  }'

(User creation is open — no auth required.)

4. Check Auth Status¶

curl http://localhost:8000/api/v1/auth/check-auth -b cookies.txt

Returns {"authenticated": true, "user": {...}, "session": {...}} when logged in.

5. Log Out¶

curl -X POST "http://localhost:8000/api/v1/auth/logout" -b cookies.txt -c cookies.txt

API Keys¶

For programmatic access (machine-to-machine clients), create an API key while logged in:

curl -X POST "http://localhost:8000/api/v1/api-keys/" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "My Integration Key",
    "permissions": {},
    "usage_limits": {}
  }'

⚠️ The full API key is shown once in the response. Store it securely.

List your keys:

curl http://localhost:8000/api/v1/api-keys/ -b cookies.txt

Tiers and Rate Limits¶

# List tiers
curl http://localhost:8000/api/v1/tiers/

# Get a tier by name
curl http://localhost:8000/api/v1/tiers/free

# List rate limits
curl http://localhost:8000/api/v1/rate-limits/

Caching¶

Repeat a request twice and watch the timing — the second one should hit Redis:

curl http://localhost:8000/api/v1/users/johndoe -b cookies.txt -w "\nTime: %{time_total}s\n"
curl http://localhost:8000/api/v1/users/johndoe -b cookies.txt -w "\nTime: %{time_total}s\n"

Background Tasks (Taskiq)¶

Background processing is enabled out of the box but no example endpoint ships with the starter. To register and dispatch your own task, see Background Tasks.

To start a worker locally:

cd backend
uv run taskiq worker infrastructure.taskiq.worker:default_broker

Adding Your First Feature Module¶

The codebase uses vertical-slice modules — each feature owns its models, schemas, CRUD, service, and routes in one folder under backend/src/modules/.

For a step-by-step walkthrough of adding a new module, see the Development Guide.

Debugging Common Issues¶

Application Logs¶

docker compose logs -f web

Database Logs¶

docker compose logs -f db

Run Migrations Manually¶

If you need to re-run migrations:

cd backend
uv run alembic upgrade head

Reset Everything (Docker)¶

cd backend
docker compose down -v   # ⚠️ wipes the database volume
docker compose up

Next Steps¶

You've verified your install and tested the main features. Now:

Essential Reading¶

1. Project Structure - How the code is organized
2. Database Guide - Models, schemas, CRUD
3. Authentication - Sessions, OAuth, API keys

Advanced Features¶

1. Caching - Redis-backed cache
2. Background Tasks - Async jobs with Taskiq
3. Rate Limiting - Per-tier rate limits

Development Workflow¶

1. Development Guide - Extend the boilerplate
2. Testing - Test your features
3. Production - Deploy

Getting Help¶

• Check the logs for error messages
• Verify your backend/.env has the right values
• Search GitHub Issues for similar problems
• Open a new issue with details