Dev Infra

A catalog of local development services — databases, email servers, file storage, message brokers, and more — that developers can spin up on demand, one command, only the services they actually need.

make up SERVICES="postgres seaweedfs"

No monolithic stack, no running Kafka because one line in a shared docker-compose.yml requires it. Each service lives in its own directory and is started independently.

Quick start

Requires Docker with Compose v2.

make list                                 # see every available service
make up SERVICES="postgres seaweedfs"     # start just those two
make ps SERVICES="postgres"               # check status
make logs SERVICES="postgres"             # tail logs
make down SERVICES="postgres seaweedfs"   # stop them (keeps data volumes)
make down SERVICES="postgres" V=1         # stop and wipe its data volume
make up ALL=1                             # start everything
make down ALL=1                           # stop everything

Any service's defaults (ports, users, passwords) can be overridden by copying .env.example to .env at the repo root and editing it. .env is gitignored — see .env.example for the full list of variables.

Available services

Category	Service	What it is
databases	mysql	MySQL 8.4 (LTS)
databases	postgres	PostgreSQL 16
emails	mailpit	SMTP catcher + web UI, nothing leaves your machine
file-storage	seaweedfs	S3-compatible object storage
message-brokers	rabbitmq	RabbitMQ with management UI

Run make list for the live, authoritative list.

Testing

make test-unit     # scripts/services.sh's own logic — fast, no Docker
make test-smoke    # brings up every service for real and checks it works
make test          # both

See CONTRIBUTING.md for details.

Adding a service

See CONTRIBUTING.md for the full checklist. Short version: each service is services/<category>/<service>/docker-compose.yml + .env.example + README.md, with every credential a fixed, documented local-dev default (never a real secret).

AI-assisted development

This repo is set up to be worked on with AI coding assistants:

• Claude Code — CLAUDE.md
• GitHub Copilot — .github/copilot-instructions.md
• Cursor — .cursor/rules/project.mdc
• Windsurf — .windsurfrules
• Gemini CLI — GEMINI.md
• OpenAI Codex / other AGENTS.md-aware tools — AGENTS.md

All of the above point back to AGENTS.md, the single canonical instructions file, so there's one place to update project conventions.

Security

These services are for local development only — fixed, publicly-known default credentials, no hardening, not safe to expose to the internet. See SECURITY.md for how to report a vulnerability and what "secure" means in this repo's context.

License

MIT