DOCKER.md

Docker - Быстрый запуск

🚀 Запуск одной командой

docker compose up

Или через Makefile:

make up

Это запустит:

• ✅ PostgreSQL 15 на порту 5432
• ✅ Применит миграции автоматически
• ✅ Запустит FastAPI приложение на порту 8000

Приложение доступно: http://localhost:8000

---

⚡ Makefile команды

make help     # показать все команды
make up       # запустить всё
make down     # остановить
make logs     # логи
make build    # пересобрать
make migrate  # запустить миграции
make status   # статус миграций
make test     # тесты

---

📋 Основные команды

Запустить (с логами)

docker compose up

Запустить в фоне

docker compose up -d

Остановить

docker compose down

Остановить и удалить данные

docker compose down -v

Пересобрать образ

docker compose build
docker compose up

Посмотреть логи

docker compose logs
docker compose logs app
docker compose logs db

Логи в реальном времени

docker compose logs -f

---

🔧 Разработка

Только БД в Docker (рекомендуется для разработки)

Самый удобный режим - БД в Docker, приложение локально:

# Подними только БД
docker compose up db -d

# В другом терминале - запусти приложение локально
source .venv/bin/activate
python main.py

Преимущества:

• ✅ Быстрый перезапуск приложения
• ✅ Легко дебажить
• ✅ Hot-reload работает мгновенно
• ✅ Не нужно пересобирать Docker образ

Всё в Docker

Файлы монтируются в контейнер - изменения применяются автоматически.

docker compose up

Измени код → сохрани → сервер перезапустится автоматически.

Выполнить команду в контейнере

docker compose exec app python -m pytest
docker compose exec app python -m src.infrastructure.database.migration_runner status
docker compose exec db psql -U postgres -d cleanarch_db

Подключиться к БД

docker compose exec db psql -U postgres -d cleanarch_db

SQL команды:

\dt                              -- список таблиц
select * from users;             -- данные
select * from schema_migrations; -- применённые миграции

---

🗄️ Данные

Где хранятся данные?

Данные PostgreSQL хранятся в Docker volume postgres_data.

Очистить данные

docker compose down -v

Это удалит все данные БД. При следующем запуске всё начнётся с чистого листа.

Backup данных

docker compose exec db pg_dump -U postgres cleanarch_db > backup.sql

Восстановить данные

cat backup.sql | docker compose exec -T db psql -U postgres -d cleanarch_db

---

🐛 Troubleshooting

Порт 5432 уже занят

Если у вас локально запущен PostgreSQL:

Вариант 1: Остановить локальный PostgreSQL

brew services stop postgresql

Вариант 2: Изменить порт в docker-compose.yml

ports:
  - "5433:5432"  # внешний порт 5433

Порт 8000 уже занят

Измени порт в docker-compose.yml:

ports:
  - "8001:8000"

Приложение будет доступно на http://localhost:8001

Контейнер падает с ошибкой

Посмотри логи:

docker compose logs app

Пересоздать всё с нуля

docker compose down -v
docker compose build --no-cache
docker compose up

---

🏗️ Production готовность

Для production измени:

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

Создай .env.production:

DATABASE_PASSWORD=strong_password_here
DEBUG=False

Запусти:

docker compose --env-file .env.production up

2. Используй отдельную БД

Убери db из docker-compose и подключайся к внешней БД:

app:
  environment:
    DATABASE_HOST: your-db-host.com
    DATABASE_PASSWORD: ${DB_PASSWORD}

3. Добавь Nginx

Создай nginx.conf и добавь сервис в docker-compose.

---

📦 Размеры образов

docker images | grep cleanarch

Ожидаемый размер:

• cleanarch_app: ~200MB
• postgres:15-alpine: ~230MB

---

🎯 Быстрые команды

С Makefile

make up          # запустить
make down        # остановить
make logs        # логи
make migrate     # миграции
make test        # тесты

Docker Compose напрямую

docker compose up -d              # запустить в фоне
docker compose down               # остановить
docker compose logs -f app        # логи приложения
docker compose exec app bash      # войти в контейнер
docker compose exec db psql -U postgres -d cleanarch_db  # БД
docker compose restart app        # перезапустить приложение

---

🔄 Workflow для команды

Первый запуск (новый разработчик)

git clone <repo>
cd python-clean-template
docker compose up

Готово! Всё работает.

Обновление зависимостей

docker compose build
docker compose up

Новая миграция

# создай SQL файл
docker compose exec app python -m src.infrastructure.database.migration_runner

---

Всё готово к работе! 🚀