mcma-compose

Dev-окружение для mycoolmusicapp — монолитный docker compose, который поднимает весь стек одной командой.

Сервисы

Сервис	Образ / контекст	Порт (хост)	Назначение
db	postgres:16-alpine	5432	PostgreSQL
redis	redis:7-alpine	6379	Брокер / кэш
api	mcma-backend	8000	FastAPI (uvicorn --reload)
worker	mcma-backend	—	arq-воркер фоновых задач
webui	mcma-webui	—	Rsbuild dev-сервер (HMR)
nginx	nginx:1.27-alpine	80	Единая точка входа → http://localhost

Все изменения в mcma-backend/ и mcma-webui/ применяются без перезапуска контейнеров — источники смонтированы напрямую.

---

Быстрый старт

Требования: Docker ≥ 25, docker compose (v2).

git clone --recurse-submodules <repo-url>
cd mcma-compose

make up          # создаёт .env из .env.example, собирает образы, запускает стек

После старта:

• UI → http://localhost
• API docs → http://localhost/api/docs
• API напрямую → http://localhost:8000/docs

Первый make up скачает базовые образы и соберёт api/webui — это занимает несколько минут. Повторный запуск быстрее.

Миграции

make migrate                      # накатить все pending-миграции
make makemigration m="add_tracks" # сгенерировать новую миграцию
make downgrade                    # откатить последнюю миграцию

---

Структура репозитория

mcma-compose/
├── docker-compose.yml   # dev-стек
├── nginx.conf           # роутинг /api → api:8000, / → webui:3000
├── .env.example         # шаблон переменных окружения
├── Makefile             # все команды для работы с проектом
├── mcma-backend/        # Python / FastAPI (submodule)
└── mcma-webui/          # TypeScript / React (submodule)

---

Makefile — справка по командам

Полный список всегда доступен через make или make help.

Жизненный цикл

Команда	Что делает
make up	Создать .env (если нет) → собрать образы → запустить стек
make build	Пересобрать образы (с кэшем)
make rebuild	Пересобрать образы без кэша
make down	Остановить и удалить контейнеры
make stop	Остановить контейнеры (не удалять)
make restart	Перезапустить все сервисы
make ps	Статус контейнеров

Логи

Команда	Что делает
make logs	Хвост логов всех сервисов
make logs-api	Логи только api
make logs-webui	Логи только webui

Оболочки и базы

Команда	Что делает
make sh-api	bash внутри контейнера api
make sh-webui	sh внутри контейнера webui
make db-shell	psql в базу данных
make redis-cli	redis-cli

Миграции (Alembic)

Команда	Что делает
make migrate	alembic upgrade head
make makemigration m="..."	Автогенерация миграции с сообщением
make downgrade	Откат на одну миграцию назад

Качество кода

Команда	Что делает
make test	Запустить все тесты (backend + frontend)
make test-api	pytest
make test-webui	npm test
make lint	ruff + npm run lint
make fmt	ruff format + npm run format

Очистка

Команда	Что делает
make clean	down -v — удаляет контейнеры и тома (данные БД уничтожаются)
make prune	docker system prune — чистит dangling-образы и build-кэш

Prod-сборка

make prod-build          # собрать оба prod-образа
make prod-build-api      # только mcma-backend:prod
make prod-build-webui    # только mcma-webui:prod

Prod-образы собираются напрямую из dockerfiles/Dockerfile.prod — отдельного prod-compose пока нет.

---

Переменные окружения

.env создаётся автоматически при первом make up. Ключевые переменные:

POSTGRES_USER=mcma
POSTGRES_PASSWORD=mcma
POSTGRES_DB=mcma
POSTGRES_PORT=5432

REDIS_PORT=6379

Внутри compose-сети api и worker используют DATABASE_URL и REDIS_URL с именами сервисов (db, redis), значения из .env переопределяются автоматически — менять их не нужно.