Развернуть FastAPI приложение на Docker‑Compose: пошаговый гид

Если вы хотите развернуть fastapi docker compose в продакшн‑окружении, этот гид покажет вам каждый шаг, от написания Docker‑compose файла до конфигурации Nginx как реверс‑прокси. FastAPI – быстрый и современный фреймворк, а Docker‑Compose позволяет быстро масштабировать и управлять зависимостями. В результате вы получите надежное, масштабируемое приложение, работающее через Uvicorn и защищённое Nginx.

Разбор задачи

Наша цель – собрать готовое решение, где FastAPI будет обслуживаться Uvicorn, а Nginx проксирует запросы, обеспечивая SSL, балансировку нагрузки и статические файлы. Мы будем использовать Docker‑Compose для одновременного запуска двух сервисов: backend (FastAPI) и proxy (Nginx). Это упрощает деплой, позволяет конфигурировать переменные окружения и управлять версиями контейнеров.

Пошаговое решение

1. Создайте структуру проекта. В корне проекта разместите папки app (FastAPI код), nginx (конфигурация Nginx) и docker-compose.yml. Это позволит удобно хранить все исходники и настройки в одном репозитории.
2. В папке app добавьте минимальный main.py с простым эндпоинтом. FastAPI автоматически создаст OpenAPI спецификацию, которую можно проверять через /docs.
3. Создайте Dockerfile для backend: используйте официальный образ python:3.11-slim, установите зависимости через pip install fastapi uvicorn[standard] и запустите uvicorn main:app --host 0.0.0.0 --port 8000. Это гарантирует, что приложение доступно внутри сети Docker.
4. В папке nginx подготовьте default.conf, где прописывается проксирование http://fastapi:8000. Укажите заголовки, таймауты и SSL‑сертификаты, если они нужны.
5. Напишите docker-compose.yml с двумя сервисами: fastapi (build: ./app, порты 8000) и nginx (build: ./nginx, порты 80/443). Укажите зависимости depends_on: - fastapi, чтобы Nginx запускался после backend.
6. Запустите docker compose up -d и проверьте доступность http://localhost/docs и http://localhost/health. Если всё работает, ваш FastAPI уже развернут через Docker‑Compose и доступен через Nginx. Если нужно, добавьте healthcheck в Dockerfile и restart: always в compose для автоматического перезапуска при сбоях.

Рабочий код

# docker-compose.yml
version: "3.9"
services:
  app:
    build: .
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload
    volumes:
      - .:/app
    environment:
      - PYTHONUNBUFFERED=1
    depends_on:
      - db
    networks:
      - backend
  nginx:
    image: nginx:stable-alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
    networks:
      - backend
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: appdb
    volumes:
      - db_data:/var/lib/postgresql/data
    networks:
      - backend
networks:
  backend:
    driver: bridge
volumes:
  db_data:
    driver: local

# nginx.conf
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://app:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /app/static/;
    }
}

Типичные ошибки

• Неправильная ссылка в proxy_pass – убедитесь, что имя сервиса совпадает с именем в docker-compose.yml.
• Отсутствие переменной PYTHONUNBUFFERED – stdout буферизуется, лог не появляется.
• Неверный порт в command – если вы меняете порт, обновите proxy_pass.
• Запуск без --reload в продакшене – он подвесит контейнер при ошибках.
• Мало ресурсов для db – PostgreSQL требует достаточного объёма диска.

FAQ

Как добавить HTTPS?

Можно добавить сервис certbot и изменить nginx.conf, либо использовать nginx-proxy с acme-companion. Важно выставить listen 443 ssl; и указать пути к сертификатам.

Что делать, если контейнер «app» падает?

Проверьте логи: docker compose logs app. Часто причина – неверный PYTHONPATH или отсутствие зависимостей. Если используется --reload, убедитесь, что монтируемая папка не содержит синтаксических ошибок.

Можно ли использовать PostgreSQL в облаке?

Да. Замените сервис db на переменные окружения DATABASE_URL и удалите depends_on. В main.py подключайте через asyncpg или SQLAlchemy.

Заключение

Развертывание FastAPI на Docker‑Compose с Uvicorn и Nginx – это стабильный, масштабируемый подход. Следуйте чек‑листу:

1. Проверьте docker-compose.yml – корректно ли указаны сервисы и сети.
2. Убедитесь, что proxy_pass указывает на правильный сервис и порт.
3. Запустите docker compose up --build и проверьте docker compose ps.
4. Проверьте логи: docker compose logs -f app.
5. Настройте мониторинг (Prometheus, Grafana) и логирование (ELK).
6. Реализуйте CI/CD для автоматической сборки и деплоя.