From eae0db649a4257c18c0a9e30750ede4e09e5b3be Mon Sep 17 00:00:00 2001
From: Senko-san <senko@Senko-sans-Mac-mini.local>
Date: Sat, 6 Jun 2026 13:52:54 +0300
Subject: [PATCH] Create README.md

---
 README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cbeb34b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,146 @@
+# 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).
+
+```bash
+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` — это занимает несколько минут. Повторный запуск быстрее.
+
+### Миграции
+
+```bash
+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-сборка
+
+```bash
+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`. Ключевые переменные:
+
+```dotenv
+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` переопределяются автоматически — менять их не нужно.