// Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology.
Write or modify Oscilla game content YAML manifests for any game package. Use when: creating a new game package, writing adventures, enemies, items, quests, regions, locations, skills, buffs, archetypes, recipes, loot tables, or conditions; designing progression systems; configuring game.yaml or character_config.yaml; authoring template expressions; setting up cooldowns or passive effects; validating content with the CLI; or any task that touches files under a content/ game package directory.
Create or modify FastAPI routes in the Oscilla codebase. Use when: adding new API endpoints, creating Pydantic request/response models, registering routers, designing REST APIs, or following route conventions for this project.
Work on the Oscilla frontend (SvelteKit/Vite). Use when: writing or modifying any Svelte components, routes, stores, styles, or frontend tests; adding new UI features or pages; fixing frontend bugs; running frontend tests or type checks; managing npm dependencies; working on accessibility or usability; building production assets; or any task that touches files under frontend/.
Complete reference for all make targets in the Oscilla project. Use when: looking up the right make command for any task — setup, testing, linting, formatting, database, frontend, packaging, or cleanup.
Use the Oscilla CLI to assist content authors writing YAML manifests. Use when: setting up JSON schema validation for YAML manifests, running validate or oscilla content test, inspecting manifest content with list/show, tracing adventure paths, graphing world structure, scaffolding new manifests with oscilla content create, debugging content errors, checking cross-references. Knows all oscilla content subcommands: schema, test, list, show, graph, trace, create. Also covers oscilla validate.
Add or modify application configuration settings in Oscilla. Use when: adding new environment variables, adding new settings fields, understanding settings conventions, working with secrets, or configuring optional vs required settings.
| name | docker-compose |
| description | Work with the Oscilla Docker Compose development environment. Use when: starting or stopping services, inspecting logs, opening a shell in a container, resetting the database, or understanding the service topology. |
context7: If the
mcp_context7tool is available, resolve and load the full Docker Compose documentation before modifyingcompose.yamlor using advanced CLI options:mcp_context7_resolve-library-id: "docker compose" mcp_context7_get-library-docs: /docker/compose
The Oscilla development environment runs entirely through Docker Compose. All services are defined in compose.yaml.
| Service | Role |
|---|---|
gateway | Caddy reverse proxy — routes traffic to backend/frontend |
backend | FastAPI application server |
frontend | Vite / SvelteKit dev server |
db | PostgreSQL database |
redis | Redis cache / task queue |
mailhog | Local SMTP sink for catching outbound emails |
# Start all services in the background
docker compose up -d
# Stop all services (preserves volumes — data is retained)
docker compose down
# Stop all services AND remove volumes (full reset — destroys all data)
docker compose down -v
# Restart all services without destroying containers or volumes
docker compose restart
# Restart a single service
docker compose restart backend
# View recent logs from all services
docker compose logs
# Follow (tail) logs from all services in real-time
docker compose logs -f
# Follow logs from a specific service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f db
# List running services and their status
docker compose ps
# Open a bash shell inside a running service
docker compose exec backend bash
docker compose exec db bash
docker compose exec frontend sh
docker compose up -d
docker compose logs -f # watch until all services are healthy
docker compose down -v
docker compose up -d
docker compose logs backend --tail=50
# or follow real-time:
docker compose logs -f backend
docker compose exec backend bash
# then run commands inside the container
docker compose exec backend uv run alembic upgrade head
Caddy) handles TLS termination and routing. Its config lives in docker/gateway/Caddyfile.docker/frontend/Dockerfile.docker/ folder..env file is loaded automatically by Compose — make sure it's populated before starting.