feature: make dev — api и worker на хосте с видимым окном Chrome (#90)

- docker-compose.dev.yml: порты rabbitmq, redis, postgres на 127.0.0.1 (5673, 6380, 5433 —
  стандартные часто заняты другими проектами)
- make dev: останавливает контейнерные api и worker (иначе worker в Docker тоже берёт задачи
  из общей очереди и выполняет их невидимо), поднимает инфраструктуру, запускает uvicorn --reload
  на :8010 и воркер dramatiq; Ctrl+C останавливает оба
- make dev-key name=...: API-ключ без контейнера api
- README: раздел Local development

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Makefile

@@ -5,10 +5,10 @@ WHEELS_DIR := wheels
 REQUIREMENTS := requirements.txt
 ver ?= latest
 
-MAKECMDGOALS_TARGETS := install freeze wheels sync sync-offline clean help build release sync-dev test test-browser up down logs smoke key-create key-list key-revoke stats push
+MAKECMDGOALS_TARGETS := install freeze wheels sync sync-offline clean help build release sync-dev test test-browser up down logs smoke key-create key-list key-revoke stats push dev dev-deps dev-key
 PKG := $(filter-out $(MAKECMDGOALS_TARGETS),$(MAKECMDGOALS))
 
-.PHONY: install freeze wheels sync sync-offline clean help venv build release sync-dev test test-browser up down logs smoke key-create key-list key-revoke stats push
+.PHONY: install freeze wheels sync sync-offline clean help venv build release sync-dev test test-browser up down logs smoke key-create key-list key-revoke stats push dev dev-deps dev-key
 
 # образы сервисов: api — без Chrome, worker — Chrome + Xvfb; rabbitmq и redis — сторонние, кладутся в релиз
 REGISTRY := docker.sokolab.xyz
@@ -18,6 +18,23 @@ DEPS_IMAGES := rabbitmq:4.1-alpine redis:8.2-alpine postgres:17-alpine
 API_URL ?= http://localhost:8000
 API_KEY ?=
 
+# make dev (#90): rabbitmq, redis, postgres — в Docker с портами на 127.0.0.1 (docker-compose.dev.yml), api и worker —
+# на хосте, Chrome открывается на рабочем столе. Порты нестандартные: 5672/5432/8000 часто заняты другими проектами.
+DEV_COMPOSE := docker compose -f docker-compose.yml -f docker-compose.dev.yml
+DEV_API_PORT ?= 8010
+DEV_RABBITMQ_PORT ?= 5673
+DEV_REDIS_PORT ?= 6380
+DEV_POSTGRES_PORT ?= 5433
+# окон Chrome на рабочем столе; потоков dramatiq — вдвое больше, как в Dockerfile
+DEV_SLOTS ?= 2
+RABBITMQ_PASSWORD ?= robotex
+POSTGRES_PASSWORD ?= robotex
+export DEV_RABBITMQ_PORT DEV_REDIS_PORT DEV_POSTGRES_PORT RABBITMQ_PASSWORD POSTGRES_PASSWORD
+DEV_ENV := RABBITMQ_URL=amqp://robotex:$(RABBITMQ_PASSWORD)@localhost:$(DEV_RABBITMQ_PORT)/ \
+	REDIS_URL=redis://localhost:$(DEV_REDIS_PORT)/0 \
+	DATABASE_URL=postgresql+asyncpg://robotex:$(POSTGRES_PASSWORD)@localhost:$(DEV_POSTGRES_PORT)/robotex \
+	BROWSER_SLOTS=$(DEV_SLOTS)
+
 help:
 	@echo "make install <pkg> [<pkg> ...]  - установить пакет(ы) в $(VENV), обновить $(REQUIREMENTS), собрать wheel в $(WHEELS_DIR)/"
 	@echo "make sync                       - установить все пакеты из $(REQUIREMENTS) (из индекса)"
@@ -31,6 +48,8 @@ help:
 	@echo "make up                         - собрать и запустить локально: api, worker, rabbitmq, redis"
 	@echo "make down                       - остановить локальный стенд"
 	@echo "make logs                       - логи api и worker"
+	@echo "make dev                        - api и worker на хосте с видимым Chrome, rabbitmq/redis/postgres в Docker; API на :$(DEV_API_PORT)"
+	@echo "make dev-key name=<клиент>      - выпустить API-ключ клиенту при make dev"
 	@echo "make smoke API_KEY=... [API_URL=...] - проверить запущенный стенд: ключ, /v1/solve, /v2/tasks, удержание окна"
 	@echo "make key-create name=<клиент>   - выпустить API-ключ клиенту (в запущенном compose)"
 	@echo "make key-list                   - клиенты и их ключи (без самих ключей)"
@@ -88,6 +107,21 @@ down:
 logs:
 	docker compose logs -f api worker
 
+# контейнерные api и worker останавливаются: иначе worker в Docker тоже берёт задачи из общей очереди и выполняет их невидимо
+dev-deps:
+	-docker compose stop api worker
+	$(DEV_COMPOSE) up -d --wait rabbitmq redis postgres
+
+# Ctrl+C останавливает оба процесса; инфраструктура остаётся запущенной (make down — остановить)
+dev: dev-deps
+	cd src && export $(DEV_ENV) && \
+		{ $(PYTHON) -m uvicorn main:app --reload --port $(DEV_API_PORT) & api=$$!; \
+		trap 'kill $$api 2>/dev/null' EXIT INT TERM; \
+		$(PYTHON) -m dramatiq worker.actors --processes 1 --threads $$(( $(DEV_SLOTS) * 2 )); }
+
+dev-key: dev-deps
+	cd src && $(DEV_ENV) $(PYTHON) -m db.cli create "$(name)"
+
 smoke:
 	$(PYTHON) tests/smoke.py $(API_URL) $(API_KEY)
 

README.md

@@ -167,14 +167,17 @@ Not done yet:
 ## Local development
 
 ```bash
-make sync-offline        # venv in ~/.py_envs/robotex; another path: make VENV=... <target>
+make sync-offline              # venv in ~/.py_envs/robotex; another path: make VENV=... <target>
-docker compose up -d rabbitmq redis                       # queue and storage
+make dev                       # api + worker on the host, Chrome windows visible on your desktop; API on :8010
-cd src && RABBITMQ_URL=... REDIS_URL=... uvicorn main:app --reload
+make dev-key name=local        # API key for it (stored in the same postgres volume as make up)
-cd src && dramatiq worker.actors --processes 1 --threads 4
 ```
 
-The compose network is not published, so for running the services on the host publish `5672` and `6379` yourself,
+`make dev` stops the containerized api and worker (otherwise the Docker worker also takes tasks from the common
-or just use `make up`. Chrome runs headful, so a display is required (locally — your desktop, in Docker — Xvfb).
+queue and runs them invisibly), starts rabbitmq, redis and postgres with ports published on 127.0.0.1
+(`docker-compose.dev.yml`: 5673, 6380, 5433), then runs uvicorn with `--reload` and the dramatiq worker in the
+foreground. Ctrl+C stops both; `make down` stops the infrastructure. Ports, slots: `DEV_API_PORT`,
+`DEV_RABBITMQ_PORT`, `DEV_REDIS_PORT`, `DEV_POSTGRES_PORT`, `DEV_SLOTS` (default 2). Chrome runs headful, so a display
+is required (locally — your desktop, in Docker — Xvfb).
 
 Tests:
 

docker-compose.dev.yml

@@ -0,0 +1,15 @@
+# Локальная разработка (make dev, #90): поверх docker-compose.yml открывает порты rabbitmq, redis и postgres
+# на 127.0.0.1, чтобы api и worker запускались на хосте — с видимым окном Chrome на рабочем столе.
+# Порты нестандартные: 5672/5432 на хосте часто заняты другими проектами.
+services:
+  rabbitmq:
+    ports:
+      - "127.0.0.1:${DEV_RABBITMQ_PORT:-5673}:5672"
+
+  redis:
+    ports:
+      - "127.0.0.1:${DEV_REDIS_PORT:-6380}:6379"
+
+  postgres:
+    ports:
+      - "127.0.0.1:${DEV_POSTGRES_PORT:-5433}:5432"