Environment Setup and Run

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• src/osu_server/config.py
• src/athena_cli/commands/env.py
• pyproject.toml
• CLAUDE.md
• tests/unit/athena_cli/test_env_generation.py

Athena provides a multi-layered environment management system designed for reproducible local development and scalable production deployments. The setup relies on a combination of Nix for system-level dependencies, uv for Python package management, and a custom CLI (athena_cli) for orchestrating environment configuration and database tasks.

The environment is structured as a two-process model consisting of an application process (uvicorn) for immediate request handling and a worker process (taskiq) for heavy background tasks. All runtime state and configuration are driven by environment variables, which are typically managed through .env.{environment} files.

Sources: README.md:96-110, AGENTS.md:389-392, src/osu_server/config.py:1-10

Development Environment Initialization

The project uses Nix flakes to provide a reproducible shell that includes all necessary services and tools. Within this shell, uv manages the Python virtual environment and dependencies.

Toolchain Setup

To enter the development environment, users utilize the following sequence:

1. Nix Shell: Run nix develop to enter a shell with pre-configured system dependencies.
2. Dependency Sync: Run uv sync to install Python dependencies into a local .venv.
3. Environment File: Initialize local settings by copying the example file or using the CLI.

Sources: README.md:94-100, AGENTS.md:39-41, CLAUDE.md:12-16

Dependency and Environment Flow

The following diagram illustrates the relationship between the development tools and the runtime environment:

This diagram shows how Nix provides the foundation for the local toolchain, which then manages the application environment and its connection to infrastructure.
Sources: README.md:96-105, CLAUDE.md:12-20

Configuration Management

Athena uses pydantic-settings to load and validate configuration from environment variables. The AppConfig class serves as the central authority for all runtime settings, ensuring type safety and providing sensible defaults.

Environment Variable Requirements

Required variables must be defined for the application to start. The project supports different environment profiles (e.g., development, test, production), which determine which .env.{environment} file is loaded.

Variable	Type	Description
DATABASE_URL	PostgresDsn	Connection string for PostgreSQL (asyncpg).
VALKEY_URL	RedisDsn	Connection string for Valkey/Redis instance.
ENVIRONMENT	str	Profile name (default: development).
DOMAIN	str	Base domain for the server (default: athena.localhost).

Sources: src/osu_server/config.py:27-37, README.md:103-107, src/athena_cli/commands/env.py:100-112

The Athena CLI (athena_cli)

The CLI provides commands to manage environment files interactively or non-interactively.

# Generate an example env file
uv run athena env example

# Interactively initialize a new environment file
uv run athena env init development

# Generate env file from existing process environment variables
uv run athena env init production --non-interactive

Sources: src/athena_cli/commands/env.py:21-65, README.md:113-116

Running Services and Processes

The application utilizes a process-compose setup to manage multiple local services simultaneously.

Core Services

When running process-compose up, the following components are started:

• PostgreSQL: Primary persistent storage for domain models.
• Valkey: Infrastructure for sessions, presence, and task queues.
• App Process: The Starlette/FastAPI web server.
• Worker Process: The taskiq worker for background processing.
• Nginx/Cloudflared: Ingress and tunneling adapters.

Sources: AGENTS.md:44-45, README.md:110-112, src/osu_server/config.py:1-10

Execution Flow

The following sequence diagram shows the startup and interaction flow between the core processes:

This diagram demonstrates the orchestration of infrastructure and application processes by process-compose.
Sources: AGENTS.md:44-55, README.md:31-38, AGENTS.md:389-392

Quality Gates and Verification

Before code is considered ready for the environment, it must pass a series of quality gates. These are enforced both locally via scripts and in CI.

Local Quality Commands

The project provides a unified script for running checks:

• Quality Gate: ./scripts/ci.sh quality (Runs ruff, basedpyright, and import-linter).
• Test Gate: ./scripts/ci.sh test (Runs pytest).
• Git Hooks: prek run --all-files (Runs all checks before commit).

Sources: README.md:118-128, AGENTS.md:63-68, pyproject.toml:50-80

Database Migrations

Database schema changes are managed via Alembic:

# Apply migrations
uv run alembic upgrade head

# Generate a new migration
uv run alembic revision --autogenerate -m "description"

Sources: README.md:130-137, AGENTS.md:74-76

Summary

The Athena environment setup is heavily automated through Nix and the athena_cli. By separating configuration into distinct environment profiles and utilizing a two-process model for runtime execution, the project ensures that local development closely mirrors the requirements of a horizontally scalable production system. Developers should prioritize the use of the provided CLI tools and Nix shell to maintain consistency across the codebase.