21-python — Python 3 (venv, pip, dev) + pipx

Ставит интерпретатор Python 3 с инструментами для виртуальных окружений и сборки пакетов; рантайм для пресетов fastapi и django команды mitdev app. ☐ опциональный модуль.

Зачем нужен #

Python — язык, на котором написаны FastAPI, Django и множество бэкенд-сервисов. Модуль ставит сам интерпретатор python3, средство создания virtualenv (изолированного окружения: отдельная папка с копией Python и своим набором пакетов, чтобы зависимости приложений не конфликтовали друг с другом и с системой), pip (менеджер пакетов), заголовочные файлы для сборки пакетов из исходников (-dev/-devel) и pipx (утилита для установки Python-CLI-приложений, каждое в свой изолированный venv).

Приложения при этом работают не в системном Python, а в собственном виртуальном окружении .venv, которое создаёт mitdev app. Этот модуль лишь даёт базу для их создания.

Когда включать и когда не нужен #

Включайте для развёртывания FastAPI, Django или другого Python-приложения (пресеты fastapi, django в mitdev app).

Не нужен, если Python-приложений нет. Отдельно ставить не обязательно ради самого python3 — он и так есть в системе (см. ниже), но модуль добавляет venv/pip/dev/pipx, без которых полноценно развернуть приложение не получится.

Зависимости и требования #

• Для реального запуска приложения нужны модули 07-pm2 (приложение работает под PM2), 06-nginx (reverse-proxy) и 08-certbot (HTTPS).
• База данных — отдельными модулями (12-postgresql и т.п.).
• Компилятору расширений могут потребоваться базовые build-инструменты (ставятся модулем 01-system/11-utils).

Что именно делает #

Шаги module_install (файл modules/21-python.sh):

1. Установка Python 3.
   • Debian/Ubuntu: python3 python3-venv python3-pip python3-dev.
   • RHEL/SUSE: python3 python3-pip python3-devel.
2. Установка pipx. На Debian ставится, если ещё не установлен (пакет есть с Ubuntu 23.04 / Debian 12); на RHEL — отдельным шагом. Если pipx недоступен в репозитории, шаг пропускается с предупреждением (не критично).
3. Верификация и отметка модуля.

Пакет -venv (Debian) даёт модуль venv для создания виртуальных окружений; -dev/-devel — заголовки C, нужные, когда pip собирает пакеты с нативными расширениями (например psycopg2, cryptography).

Файлы, службы и порты #

Служб модуль не создаёт (интерпретатор — не демон). Порт (по умолчанию 8000) открывает само приложение, проксируемое через nginx.

Настройка #

Собственных переменных defaults.conf у модуля нет — ставится системная версия Python 3 дистрибутива. Версия и параметры зависят от репозитория ОС.

Как переопределить настройки #

Модуль вопросов не задаёт. Установить его отдельно после первичной настройки:

sudo mitdev add python

Версию Python при необходимости меняют средствами дистрибутива (например deadsnakes PPA на Ubuntu) — это вне модуля. Зависимости приложения фиксируются в его requirements.txt.

Проверка, что всё работает #

Автоматическая верификация проверяет наличие python3, работоспособность python3 -m venv и python3 -m pip.

Вручную:

python3 --version                        # напр. Python 3.12.x
python3 -m pip --version                 # версия pip
python3 -m venv --help >/dev/null && echo venv-ok
pipx --version                           # если pipx установился

Развёртывание приложения на этом рантайме #

Установлены модули python, pm2, nginx, для HTTPS — certbot.

FastAPI #

# 1. Развернуть (пресет fastapi, порт по умолчанию 8000):
sudo mitdev app fastapi api https://github.com/you/api.git api.example.com

Что произойдёт:

• репозиторий клонируется в ~deploy/apps/api;
• создаётся виртуальное окружение .venv (python3 -m venv .venv);
• если есть requirements.txt — .venv/bin/pip install -r requirements.txt;
• ставится uvicorn (ASGI-сервер) и приложение запускается под PM2 командой .venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 (ожидается объект app в main.py; иначе задайте свою команду в файле ~deploy/apps/api/.mitdev/start);
• nginx получает reverse-proxy api.example.com → 127.0.0.1:8000;
• предлагается выпустить SSL.

Django #

# 1. Развернуть (пресет django):
sudo mitdev app django site https://github.com/you/site.git site.example.com

Что произойдёт: то же создание .venv и установка requirements.txt, но ставится gunicorn (WSGI-сервер), а команда запуска собирается автоматически из найденного wsgi.py: .venv/bin/gunicorn <проект>.wsgi --bind 127.0.0.1:8000.

# 2. Настроить окружение и БД (данные PostgreSQL — в /root/.mitdev-credentials):
sudo cat /root/.mitdev-credentials
sudo -u deploy nano ~deploy/apps/site/.env      # DATABASE_URL и т.п.

# 3. Миграции и статика Django (пример):
sudo -u deploy bash -lc 'cd ~/apps/site && .venv/bin/python manage.py migrate --noinput && .venv/bin/python manage.py collectstatic --noinput'
sudo -u deploy -i pm2 restart site

# 4. Сертификат (если не выпустили при app):
sudo mitdev ssl site.example.com [email protected]

# 5. Обновление после push:
sudo mitdev deploy site

Логи приложения:

sudo -u deploy -i pm2 logs api           # stdout/stderr uvicorn/gunicorn
mitdev logs pm2
sudo tail -f /var/log/nginx/api.error.log

Типовые задачи #

# Пересоздать окружение и переустановить зависимости:
sudo -u deploy bash -lc 'cd ~/apps/api && rm -rf .venv && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt'
sudo -u deploy -i pm2 restart api

# Добавить пакет в окружение приложения:
sudo -u deploy bash -lc 'cd ~/apps/api && .venv/bin/pip install httpx && .venv/bin/pip freeze > requirements.txt'

# Задать свою команду запуска (если автоопределение не подошло):
sudo -u deploy bash -lc 'mkdir -p ~/apps/api/.mitdev && echo ".venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000" > ~/apps/api/.mitdev/start'
sudo mitdev deploy api

# Установить CLI-утилиту глобально через pipx (изолированно):
sudo -u deploy -i pipx install poetry

# Посмотреть логи и перезапустить:
sudo -u deploy -i pm2 logs api
sudo -u deploy -i pm2 restart api

Частые ошибки #

Симптом: при развёртывании — «Не удалось определить команду запуска». Причина: для FastAPI нет объекта app в main.py, для Django не найден wsgi.py. Решение: создайте файл ~deploy/apps/<app>/.mitdev/start с одной строкой — командой запуска, затем sudo mitdev deploy <app>.

Симптом: pip install падает с ошибками компиляции (gcc, Python.h not found). Причина: пакет собирается из исходников, не хватает заголовков или компилятора. Решение: модуль ставит python3-dev/-devel; убедитесь, что есть build-инструменты (sudo mitdev add utils или установите build-essential).

Симптом: приложение не стартует, pm2 logs показывает ModuleNotFoundError. Причина: зависимость не установлена в .venv (или venv пересоздан без переустановки). Решение: sudo -u deploy bash -lc 'cd ~/apps/api && .venv/bin/pip install -r requirements.txt', затем pm2 restart.

Симптом: pipx: command not found. Причина: pipx недоступен в репозитории дистрибутива (старая версия ОС). Решение: это не ошибка модуля; поставьте pipx через pip: python3 -m pip install --user pipx.

Безопасность и продакшен #

• Каждое приложение — в своём .venv, изолированно от системного Python и других приложений. Не ставьте зависимости приложения в системный Python.
• Приложение слушает 127.0.0.1 и публикуется только через nginx; порт приложения в файрволе не открывайте.
• Не запускайте приложения от root — mitdev app работает от deploy.
• Фиксируйте зависимости в requirements.txt (или lock-файле) и следите за обновлениями безопасности.

Откат и удаление #

module_rollback — пустой (no-op): python3 на современных дистрибутивах является жёсткой системной зависимостью, поэтому при сбое установки интерпретатор не трогается.

Ручное удаление:

sudo mitdev remove python            # ничего не удаляет — только сообщение
sudo mitdev remove python --purge    # удаляет python3-venv/pip/dev/pipx, но НЕ сам python3

Почему python3 не удаляется: от него зависят системные утилиты (apt, cloud-init, инструменты дистрибутива). Удаление интерпретатора сломало бы систему, поэтому module_remove без --purge — no-op, а с --purge убирает только добавленные mitdev вспомогательные пакеты (python3-venv, python3-pip, python3-dev, pipx), оставляя интерпретатор на месте. Виртуальные окружения .venv в каталогах приложений не трогаются.

См. также #

• ../COMMANDS.md — команды mitdev app fastapi|django, deploy, ssl.
• ../RECIPES.md — сквозные сценарии развёртывания.
• 07-pm2.md — менеджер процессов, под которым работает приложение.
• 06-nginx.md, 08-certbot.md — reverse-proxy и SSL.