FastAPI + Docker с нуля: деплоим свой первый API без боли и слез

Привет, Хабр! Если вы недавно начали кодить на Python, пробуете себя в бэкенде, а от слова «контейнеризация» хочется закрыть ноутбук и уйти в лес — вы по адресу. Эта статья для тех, кто хочет понять базу без заумных терминов и сложной архитектуры.

Что мы будем делать? Мы с нуля напишем простейшее API и упакуем его в Docker. Грубо говоря, засунем наш код в изолированную коробочку. Эту коробку вы потом сможете запустить на макбуке, винде или сервере на Linux — и она гарантированно заведется и будет работать везде абсолютно одинаково.

Почему именно FastAPI? Потому что сейчас это идеальный фреймворк для старта. Он быстрый, современный и не перегружен лишними правилами. А самое крутое — он «из коробки» генерирует красивую автодокументацию (тот самый Swagger). Вы просто пишете пару строчек кода, а FastAPI сам собирает веб-интерфейс, где ваше API можно удобно потыкать кнопочками.

А зачем нам Docker? Каждый разработчик рано или поздно сталкивается с классической болью: «Ну не знаю, на моем компе всё работало!». Вы скидываете код на сервер (или другу), а там — другая версия питона, забыли поставить библиотеку, криво встали зависимости, и всё падает.

Docker убивает эту проблему на корню. Он берет ваше приложение, все нужные ему библиотеки и правильную версию Python, а затем запаковывает всё это в один стандартный образ. В итоге вы деплоите не просто скрипты, а готовую и настроенную рабочую среду.

Шаг 0: Подготовка рабочего места

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

1. Python (версия 3.10 и выше) FastAPI активно использует современные фишки языка (например, аннотации типов), поэтому старичок Python 3.8 тут не подойдет. Если у вас установлена старая версия — самое время обновиться.

2. Адекватный редактор кода (IDE) Идеально подойдут VS Code или PyCharm. Если вы привыкли хардкорить в Vim или писать код во встроенном блокноте Windows — мое почтение, но для старта лучше взять инструмент, который сам подсветит ошибки и подставит нужные скобочки.

3. Docker Desktop Тот самый герой нашей статьи. Идем на официальный сайт, скачиваем версию под свою операционку (Windows, Mac или Linux) и устанавливаем как обычную программу. После установки его нужно запустить — в трее (где часики) должен появиться значок кита с контейнерами.

Как проверить, что Docker реально работает? Не верьте иконкам, верьте консоли. Откройте терминал (или командную строку в Windows) и вбейте простую команду:

docker --version

Если терминал не ругнулся красным текстом «command not found», а выдал что-то вроде Docker version 24.0.5, build ced0996 — поздравляю, вы восхитительны!

Шаг 1: Пишем код (FastAPI)

Начнем с классики. Создаем пустую папку для нашего проекта, открываем в ней терминал (или прямо в IDE) и настраиваем виртуальное окружение. Это нужно, чтобы не ставить библиотеки глобально в систему и не устраивать там свалку.

Вбиваем в консоль:

# Создаем виртуальное окружение (папочка venv появится в вашем проекте)python -m venv venv# Активируем его (для Windows)venv\Scripts\activate# Или для Mac/Linuxsource venv/bin/activate

Отлично, мы в «песочнице». Теперь ставим сам фреймворк и веб-сервер, который будет его запускать:

pip install fastapi uvicorn

А теперь очень важный момент, про который новички часто забывают. Докеру в будущем понадобится точный список того, что мы тут сейчас установили. Поэтому сразу «замораживаем» наши зависимости и записываем их в текстовый файл:

pip freeze > requirements.txt

В вашей папке появится файл requirements.txt. Это буквально список покупок для Докера, чтобы он знал, какие версии библиотек ему нужно будет скачать внутрь контейнера.

Теперь пишем сам код. Создайте файл main.py и вставьте туда эти 5 строчек:

from fastapi import FastAPI# Создаем само приложениеapp = FastAPI()# Вешаем обработчик на главную страницу@app.get("/")def read_root():    return {"message": "Hello, Habr!"}

Всё! Этого достаточно для полноценного API. Давайте проверим, что оно работает локально, прежде чем пихать его в контейнер. Запускаем сервер:

uvicorn main:app --reload

• main — это имя нашего файла (main.py).

• app — переменная внутри файла, где живет FastAPI.

• --reload — полезный флаг для разработки: сервер будет сам перезапускаться, если вы измените код.

Открываем браузер и переходим по адресу [http://127.0.0.1:8000](http://127.0.0.1:8000). Там вы увидите заветную строчку {"message": "Hello, Habr!"}.

Но настоящая фишка FastAPI прячется по другому адресу. Допишите в адресной строке /docs (чтобы получилось [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)), и вы попадете в Swagger UI.

Это та самая интерактивная автодокументация. Вам не пришлось писать для нее ни строчки кода, а FastAPI уже нарисовал красивый интерфейс, где можно посмотреть все ваши маршруты, форматы ответов и даже протестировать запросы прямо из браузера (кнопка Try it out).

Шаг 2: Что такое Docker «на пальцах»

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

Представьте морские грузоперевозки лет сто назад. В порт привозят мешки с зерном, хрупкие ящики с посудой. Грузчики в панике пытаются распихать всё это по трюму. Долго, дорого, больно.

Раньше разработка выглядела точно так же. На сервере крутится старый проект на Python 3.8, а вы пытаетесь запустить туда свой новый код на Python 3.11 с кучей специфичных библиотек. Начинается конфликт версий, ломаются пути, сервер падает.

А потом в морских перевозках придумали стандартный грузовой контейнер. И всё изменилось. Теперь вы можете засунуть в этот железный ящик хоть рояль, хоть мешки с картошкой, закрыть двери и отдать портовому крану. Крану и кораблю вообще без разницы, что внутри. Они просто берут стандартный кубик и везут его.

Docker — это тот самый стандартизированный железный ящик, только для кода. Вы кладете в него свою программу, нужную именно ей версию Python, все библиотеки из requirements.txt и даже кусок операционной системы. Затем закрываете этот ящик и отправляете на любой сервер (или другу на макбук). И поскольку это стандартный контейнер, он везде запустится и будет работать абсолютно одинаково. Серверу не имеет значение, что внутри — он просто запускает изолированную коробочку.

Главное правило: Образ vs Контейнер

Это то, на чем спотыкаются 90% новичков. В Докере есть два главных понятия, которые нельзя путать:

• Образ (Image) — это чертеж, инструкция или рецепт. Это просто статический файл, в котором написано: «Возьми Linux, поставь туда Python, закинь файл main.py». Образ ничего не делает, он просто лежит на диске.

• Контейнер (Container) — это готовое блюдо, запущенный процесс. Когда вы говорите Докеру: «Эй, приготовь-ка мне приложение по этому рецепту (Образу)», он создает Контейнер.

Самое крутое, что по одному рецепту (Образу) вы можете испечь хоть 10, хоть 100 тортов (Контейнеров), и они будут работать параллельно, не мешая друг другу.

Шаг 3: Пишем Dockerfile

Теперь нам нужно объяснить Докеру, как именно собрать наш контейнер. Для этого создаем в корне проекта (там же, где лежит main.py) файл с именем Dockerfile.

Обратите внимание: файл должен называться ровно так, с большой буквы и без всяких расширений (никаких .txt или .py на конце).

Открываем этот файл и пишем в него наш «рецепт». Скопируйте этот код, а ниже мы разберем каждую строчку:

FROM python:3.11-slimWORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txtCOPY . .CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Смотрите, как всё логично. Мы буквально по шагам говорим Докеру, что делать:

• FROM python:3.11-slim — Берем основу. Нам не нужна полноценная Windows или тяжелый Linux. Мы берем специальный, урезанный (slim) образ Linux, в котором уже установлен Python 3.11. Это наш фундамент.

• WORKDIR /app — Создаем рабочую папку. Мы говорим: «Эй, Докер, создай внутри контейнера папку app и дальше делай всё внутри неё». Чтобы не раскидывать наши файлы по всей системе контейнера.

• COPY requirements.txt . — Копируем список покупок. Берем файл requirements.txt с нашего компьютера и кладем его в контейнер (точка . в конце означает «положи в текущую папку», то есть в /app).

• RUN pip install -r requirements.txt — Устанавливаем зависимости. Даем команду терминалу внутри контейнера скачать и установить FastAPI и Uvicorn.

• COPY . . — Копируем наш код. Берем всё остальное (наш main.py) и закидываем в контейнер.

  • Хитрый вопрос: почему мы не скопировали сразу всё одной командой, а разбили на два этапа? Это фишка Докера для ускорения работы (кэширование). Если вы измените пару строчек в main.py, Докер не будет заново скачивать библиотеки — он возьмет готовый шаг из памяти и просто обновит код.

• CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] — Команда для запуска. Это то, что выполнится, когда контейнер заведется.

  • Частая ошибка новичков: забыть флаг --host 0.0.0.0. Без него Uvicorn запустится только внутри контейнера, и вы с вашего компьютера до него не достучитесь. 0.0.0.0 говорит серверу: «Принимай запросы отовсюду».

Важное дополнение: фейс-контроль для Докера (.dockerignore)

Когда мы пишем COPY . . (скопировать всё), Докер послушно тащит в контейнер вообще всё, что есть в вашей папке. В том числе тяжелую папку venv с вашим локальным окружением и системный мусор вроде __pycache__.

Этого делать категорически нельзя. Контейнер сам скачивает нужные библиотеки на шаге RUN pip install. Ваша папка venv (созданная, например, под Windows) в линуксовом контейнере просто не заработает, а только раздует его размер на сотни мегабайт.

Чтобы Докер не тянул в рот всякую гадость, создайте рядом с Докерфайлом еще один файл — .dockerignore (с точкой в начале). Это аналог .gitignore.

Пишем в него всего две строчки:

venv/__pycache__/

Всё! Теперь наш код чист, рецепт готов, защита от мусора стоит. Пора собирать этот конструктор!

Шаг 4: Контейнеризация (Билд и Запуск)

Dockerfile написан, файлы готовы. Пришло время передать всё это в Докер, чтобы он создал наш образ, а затем запустил его. Открываем терминал в папке с проектом.

1. Сборка образа (Build)

Для начала нам нужно создать тот самый статичный Образ (Image) по нашему Докерфайлу. Вводим команду:

docker build -t my-fastapi-app .

Жмем Enter и смотрим, как побежали строчки в консоли — Докер пошагово выполняет инструкции из нашего Dockerfile. Пока он качает Linux и ставит библиотеки, давайте разберем, что мы сейчас написали:

• docker build — команда «собери мне образ».

• -t my-fastapi-app — флаг -t (от слова tag или title) задает имя нашему образу. Если его не указать, Докер выдаст образу нечитаемый хэш вроде a1b2c3d4..., и мы потом замучаемся его искать. А так мы назвали его красиво и понятно.

• . (Точка в конце) — это не опечатка! Это суперважный элемент. Точка говорит Докеру: «Ищи файл Dockerfile и все нужные файлы прямо здесь, в той папке, где я сейчас нахожусь». Забудете точку — Докер ругнется и ничего не соберет.

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

2. Запуск контейнера (Run)

Теперь превращаем статический Образ в живой, работающий Контейнер. Пишем в консоль:

docker run -d -p 8000:8000 my-fastapi-app

В ответ терминал выплюнет длинную строку (это уникальный ID вашего запущенного контейнера) и снова вернет вам управление. Что здесь произошло?

• docker run — команда «запусти контейнер из образа».

• my-fastapi-app — в конце мы указываем, какой именно образ хотим запустить (тот, что собрали шагом ранее).

• -d (от слова detach) — фоновый режим. Без этого флага сервер FastAPI захватит ваш терминал и будет сыпать туда логами. А если вы случайно закроете окошко терминала — сервер умрет. Флаг -d говорит Докеру: «Запусти это в фоне и не мешай мне дальше работать в консоли».

• -p 8000:8000 (от слова publish или port) — проброс портов. Это самое важное! Ваш контейнер — это наглухо изолированная коробка. Сервер FastAPI запустился внутри нее на порту 8000, но с вашего компьютера до него не достучаться. Этот флаг буквально просверливает дырку в контейнере по правилу: [Порт на моем компе] : [Порт внутри контейнера]. Если порт 8000 у вас уже занят чем-то другим, вы легко можете написать -p 8080:8000, и тогда ваше API будет доступно локально по адресу localhost:8080.

Проверяем результат!

Всё, процесс запущен! Открываем браузер и идем по знакомому адресу: http://localhost:8000/docs

Если вы видите красивую страницу Swagger со строчкой Hello, Habr! — поздравляю! Вы только что успешно завернули бэкенд на FastAPI в Docker-контейнер и запустили его. Теперь этот контейнер можно перенести на любой сервер в интернете, выполнить там одну команду docker run, и он заработает за секунду, не требуя установки Питона или настройки окружения.

Шаг 5 (Бонусный): Docker Compose для ленивых

Наш контейнер работает, но давайте будем честными: каждый раз писать в консоли docker run -d -p 8000:8000 my-fastapi-app — это неудобно.

А теперь представьте реальный проект. Туда добавятся переменные окружения (флаги -e), подключение локальных папок (флаги -v), какие-то ограничения по памяти. Ваша команда запуска разрастется на три-четыре строчки текста. Вы 100% сделаете в ней опечатку или забудете нужный флаг.

Программисты — люди ленивые, поэтому они придумали Docker Compose. Это инструмент, который позволяет описать всю эту длинную команду со всеми флагами в одном понятном текстовом файле. Этот подход называется «инфраструктура как код» (IaC).

Создайте в корне проекта (рядом с Dockerfile) файл docker-compose.yml и вставьте туда этот код:

version: '3.8'services:  api:    build: .    container_name: my-fastapi-container    ports:      - "8000:8000"    restart: always

Что мы тут написали:

• services: — блок, где мы перечисляем наши контейнеры. Пока он у нас один (назовем его api).

• build: . — мы говорим Компоузу: «Найди Dockerfile в этой же папке (точка) и собери образ сам, мне лень писать команду build».

• ports: — наш старый добрый проброс портов (как флаг -p).

• restart: always — маленькая киллер-фича. Если ваш код упадет с ошибкой или вы перезагрузите компьютер, Docker сам автоматически перезапустит этот контейнер.

Написание одной команды

Теперь забудьте про длинные заклинания сборки и запуска. Чтобы поднять проект, вы просто открываете терминал в папке с файлом docker-compose.yml и пишете:

docker compose up -d

(Примечание: в старых версиях Докера эта команда писалась через дефис — docker-compose, но сейчас это встроенный плагин).

Всё! Компоуз сам всё прочитает, сам соберет образ по Докерфайлу, сам применит все порты и запустит контейнер в фоне (благодаря флагу -d).

А когда вы наиграетесь и захотите выключить сервер, просто напишите:

docker compose down

Эта команда аккуратно остановит контейнер и удалит его за собой. Идеальная чистота.

Заключение

Давайте подведем итоги. Всего за пару шагов мы:

1. Написали работающее API на современном FastAPI.

2. Разобрались, чем Образ (рецепт) отличается от Контейнера (готового блюда).

3. Написали правильный Dockerfile и отсекли мусор через .dockerignore.

4. Упаковали код и запустили его так, что теперь он будет работать на любой машине без танцев с бубном.

5. Прикрутили Docker Compose, как это делают взрослые инженеры в продакшене.

Куда двигаться дальше? Пока наш сервис умеет только здороваться. Это отличное начало, но в реальности нам нужна база данных. В следующих статьях (если этот формат вам зайдет) мы добавим в наш docker-compose.yml второй контейнер с настоящей базой PostgreSQL, научим их общаться друг с другом, прикрутим SQLAlchemy и начнем сохранять пользователей.

Анонсы новых статей, полезные материалы, а так же если в процессе у вас возникнут сложности, обсудить их или задать вопрос по этой статье можно в моём Telegram-сообществе. Смело заходите, если что-то пойдет не так, — постараемся разобраться вместе.