Docker Compose для новичка: запускаем Python API и PostgreSQL одной командой

Docker Compose можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. Compose описывает API, базу, сеть и volume одним файлом, чтобы проект повторялся на другом компьютере без ручной установки PostgreSQL. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

depends_on не гарантирует готовность базы, localhost внутри контейнера указывает на сам контейнер, а без volume данные исчезают при пересоздании. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте два сервиса с healthcheck и постоянным volume, где FastAPI записывает заметку в PostgreSQL. Проверка: docker compose up запускает оба сервиса, healthcheck проходит, запись остаётся после перезапуска контейнеров.

Как устроен учебный проект Docker Compose

Docker Compose разделяет подготовку, основное действие, проверку ответа и сохранение результата. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

Контрольные точки: образы, сеть, готовность и данные. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией сервиса 21 октября 2026 года. Создайте compose.yaml, Dockerfile и минимальный app.py. Пароли для локального примера вынесите в .env, а этот файл добавьте в .gitignore. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://codik:codik@db:5432/codik
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: codik
      POSTGRES_PASSWORD: codik
      POSTGRES_DB: codik
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U codik -d codik"]
      interval: 5s
      timeout: 3s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Код держит подготовку отдельно от внешнего действия, поэтому ошибку можно найти на конкретном шаге. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Compose создаёт общую сеть, где имя сервиса db работает как DNS. Healthcheck показывает готовность PostgreSQL, named volume хранит каталог данных вне жизненного цикла контейнера. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Секреты и персональные данные не должны попадать в репозиторий, журнал или публичный скриншот.

Порт 5432 не нужно публиковать на хост, если к базе обращается только API. Меньше открытых портов означает меньше случайных подключений и конфликтов. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Добавьте endpoint /notes, миграцию таблицы и команду backup, которая пишет дамп в отдельный каталог. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

Полезное улучшение сохраняет исходный сценарий и добавляет одну новую проверяемую возможность. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Для production замените учебные пароли, задайте ограничения ресурсов, стратегию миграций и внешнее резервное копирование. Для закрепления откройте в API на FastAPI, в GitHub Actions для Python и в основах SQL ORDER BY.

Как изучить тему в Кодике

Сначала разберите входные данные и один успешный вызов, затем изучайте дополнительные параметры. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Перепишите ключевую функцию по памяти и проверьте её на корректном, пустом и ошибочном вводе. Базовый синтаксис закрепите через курс Python.

Что получится в итоге

Финальный экран показывает результат, состояние запроса и понятное сообщение об ошибке без раскрытия секретов.