Skip to content

Latest commit

 

History

History
229 lines (183 loc) · 16.6 KB

README.md

File metadata and controls

229 lines (183 loc) · 16.6 KB

Production: GitHub Actions → GHCR → VPS

На VPS работают PostgreSQL и Django в Docker Compose, HTTPS обслуживает существующий Nginx на хосте. Сборки на VPS нет. Бэкапы в эту конфигурацию не входят. Volumes сохраняются между обновлениями, но не защищают от потери диска или VPS.

Как работает workflow

.github/workflows/production.yml:

  • Pull request и push в master: Ruff, полный набор Django-тестов на SQLite, применение и проверка миграций на PostgreSQL 17, тесты deploy-скрипта и валидация Compose. Существующие фототесты на PostgreSQL требуют отдельного исправления: прямое закрытие streaming response закрывает тестовое соединение внутри транзакции.
  • После успешных проверок master: сборка linux/amd64 и публикация ghcr.io/moscowpython/moscowpythonpro:<полный SHA коммита>.
  • Actions → Production → Run workflow → master: проверки, сборка и публикация, затем деплой этой сборки по SSH. Push сам по себе не обновляет VPS. Запуск с другой ветки не публикует образ и не деплоит.

Деплой использует digest, полученный непосредственно при публикации, а не latest или повторно разрешённый тег. Поэтому на VPS попадает именно образ этого запуска. Ручной запуск повторно собирает выбранную версию master; это не выбор произвольного старого релиза. Production jobs сериализованы в Actions; flock дополнительно блокирует одновременный запуск скрипта на VPS. Перед SSH-деплоем workflow проверяет, что commit всё ещё является вершиной master. Если ветка уже обновилась, устаревший запуск завершится ошибкой без изменения VPS.

1. Подготовить VPS

Требуются Linux x86-64, Docker Engine, Compose v2 с поддержкой up --wait (2.20+), Bash, flock, Python 3, curl и работающий Nginx. Для ARM потребуется отдельно изменить платформу сборки. Docker должен запускаться после перезагрузки.

Создайте отдельного SSH-пользователя, например deploy, и разрешите ему запускать Docker без интерактивного sudo. Членство в группе docker фактически даёт права root — используйте отдельный ключ и ограничьте доступ к нему.

Администратор сервера один раз создаёт каталог:

sudo install -d -m 700 -o deploy -g deploy /opt/moscowpythonpro

Перенесите .env.production.example из репозитория в /opt/moscowpythonpro/.env.production, задайте владельца deploy и права 600. Заполните:

  • POSTGRES_PASSWORD: отдельный случайный hex-пароль. Например, генерируйте его через python3 -c 'import secrets; print(secrets.token_hex(32))'. Не присылайте значения в чат и не коммитьте их.
  • ALLOWED_HOSTS: ваш-домен,127.0.0.1; loopback нужен для healthcheck.
  • SITE_URL и CSRF_TRUSTED_ORIGINS: https://ваш-домен.
  • APP_PORT: свободный локальный порт, например 8000 или 8123.
  • APP_IMAGE: можно оставить пустым для workflow — deploy-скрипт передаёт digest через окружение. Для ручных команд ниже используется последний успешный digest.

Не копируйте локальный .env: production-флаги в Compose зафиксированы. SECRET_KEY задаётся в GitHub Secrets, а не в этом файле. При деплое скрипт создаёт /opt/moscowpythonpro/.env.secrets с правами 600. Для ручных команд Compose подключайте оба env-файла, причём .env.secrets — последним. Не используйте пароль со специальными URL-символами: Compose вставляет POSTGRES_PASSWORD в DATABASE_URL без URL-кодирования. Имена пользователя и БД также должны быть URL-safe; значения по умолчанию подходят. После первого запуска изменение POSTGRES_PASSWORD в файле не меняет пароль в уже созданной БД.

Production использует отдельный Compose project moscowpythonpro-production. Существующие volumes локального Compose автоматически не подключаются: если на VPS уже есть данные старого запуска, сначала нужен отдельный план переноса. Не запускайте down -v: это удалит БД и фотографии. Образ PostgreSQL закреплён digest в Compose. Его обновление — отдельное осознанное изменение с проверкой совместимости, а не побочный эффект релиза приложения.

Доступ VPS к GHCR

Для публичного пакета авторизация сервера не нужна. GitHub может создавать новые пакеты приватными — проверьте visibility после первой публикации.

Для приватного пакета войдите в GHCR под тем же Unix-пользователем deploy, которого использует workflow. Нужен GitHub PAT classic с read:packages от пользователя с доступом к пакету; при необходимости авторизуйте его для SSO:

read -rsp 'GHCR token: ' GHCR_TOKEN; echo
printf '%s' "$GHCR_TOKEN" | docker login ghcr.io -u YOUR_GITHUB_LOGIN --password-stdin
unset GHCR_TOKEN

Токен остаётся в Docker credential store/config на VPS; ограничьте доступ к аккаунту и настройте credential helper при необходимости. В GitHub Actions публикация использует временный GITHUB_TOKEN, отдельный PAT для неё не нужен.

2. Настроить существующий Nginx

Привяжите DNS домена к VPS и получите сертификат привычным для сервера способом. В существующий HTTPS server добавьте или адаптируйте:

server {
    listen 443 ssl;
    server_name python.example.com;

    # Use the certificate paths already configured on this server.
    ssl_certificate /etc/letsencrypt/live/python.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/python.example.com/privkey.pem;

    client_max_body_size 6m;

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

server {
    listen 80;
    server_name python.example.com;
    return 301 https://python.example.com$request_uri;
}

Замените домен, пути сертификатов и порт 8000 на выбранный APP_PORT. Nginx сам не подставляет переменные из .env.production. Входной X-Forwarded-Proto должен заменяться, а не передаваться от клиента. Публично открывайте 80/443 и необходимый SSH-порт, не порт приложения или PostgreSQL. После проверки sudo nginx -t примените конфигурацию штатным способом. Статика и фотографии обслуживаются приложением; отдельный Nginx alias не нужен.

3. Настроить GitHub

Создайте environment production, желательно ограничьте его веткой master и включите required reviewers, если это доступно в вашем тарифе. Добавьте environment secrets:

Secret Значение
SECRET_KEY Постоянный секрет Django: одна непустая строка без перевода строки и управляющих символов
DEPLOY_HOST DNS-имя или IPv4 VPS, без схемы и порта
DEPLOY_USER SSH-пользователь, например deploy
DEPLOY_SSH_KEY Приватный ключ отдельной deploy-пары без passphrase
DEPLOY_KNOWN_HOSTS Проверенная запись host key сервера в формате OpenSSH known_hosts

Для нового сайта сгенерируйте отдельный SECRET_KEY, например: python3 -c 'import secrets; print(secrets.token_hex(32))'. Сохраните только значение в environment secret production → SECRET_KEY. Не используйте пароль PostgreSQL как ключ Django и не генерируйте новый ключ при каждом деплое.

Если сайт уже работает, перенесите текущий SECRET_KEY из .env.production в GitHub Secrets, выполните успешный деплой и затем удалите старую запись из .env.production. Смена ключа инвалидирует существующие сессии и подписанные данные. Новый runtime env-файл имеет приоритет над старой записью; deploy-скрипт также сбрасывает унаследованный SECRET_KEY из окружения SSH-процесса. Для ручных команд не экспортируйте SECRET_KEY: переменные процесса имеют приоритет над обоими env-файлами.

Workflow передаёт ключ через SSH stdin, не через аргументы команд или логи. На VPS он атомарно записывается в .env.secrets до запуска Compose; пустое или некорректное значение останавливает деплой, не заменяя предыдущий файл. При последующей ошибке деплоя записанный runtime env-файл не откатывается. GitHub Secrets — источник значения, но ключ всё равно присутствует на VPS и в окружении контейнеров; root и пользователи с доступом к Docker могут его прочитать.

Публичную часть deploy-ключа добавьте в authorized_keys пользователя на VPS. Для нестандартного SSH-порта задайте environment variable DEPLOY_PORT (по умолчанию 22); known_hosts тогда использует [hostname]:port. Fingerprint сервера сверяйте через доверенный канал/консоль провайдера. Не используйте непроверенный ssh-keyscan непосредственно в workflow.

У репозитория должен быть разрешён запуск Actions и публикация в GHCR; для существующего пакета выдайте этому репозиторию Actions-доступ к нему. Никакие production-секреты не нужны для проверок pull request.

4. Первый запуск и последующие обновления

После попадания workflow в master дождитесь успешной публикации. Для приватного пакета настройте серверный login, затем запустите Run workflow на master.

Workflow переносит Compose и скрипт в отдельный каталог /opt/moscowpythonpro/releases/<sha>-<run-id>-<attempt>, не копируя туда секреты. Скрипт последовательно:

  1. Принимает SECRET_KEY через stdin, записывает закрытый runtime env-файл, валидирует Compose и скачивает образы.
  2. Запускает PostgreSQL и ждёт готовности.
  3. Выполняет миграции отдельным временным контейнером.
  4. Обновляет web и ждёт Docker healthcheck.
  5. Требует HTTP 200 от /health через фактический локальный порт и от главной страницы через публичный SITE_URL с проверкой TLS. Редирект считается ошибкой: SITE_URL должен указывать на конечный HTTPS origin.
  6. Только после успеха записывает current-image и current-release.

Проверка HTTPS требует доступности публичного домена с самого VPS. На первом запуске создайте администратора вручную по SSH под deploy:

cd /opt/moscowpythonpro
export APP_IMAGE="$(cat current-image)"
release="$(cat current-release)"
docker compose --project-directory "$PWD" --env-file .env.production \
  --env-file .env.secrets -f "$release/docker-compose.prod.yml" \
  exec web python manage.py createsuperuser

Для диагностики используйте тот же префикс Compose с logs --tail 100 web db или ps. Для Django security checks — exec web python manage.py check --deploy. Предупреждения HSTS subdomains/preload ожидаемы: эти параметры намеренно выключены. Не выводите полный docker compose config в публичные логи: он содержит секреты.

Ошибки и ограничения

При ошибке pull/readiness/миграций скрипт не переходит к обновлению web. Уже применённые миграции при этом не отменяются. Старая версия приложения остаётся работать во время миграций, поэтому изменения схемы должны быть обратно совместимы. Для несовместимых миграций нужен отдельный релиз с окном обслуживания.

Один web-контейнер допускает короткий простой при обновлении. Если новая версия не прошла healthcheck или HTTPS-проверку, workflow завершится ошибкой, но не откатит контейнер или БД автоматически. Файлы current-* тогда обозначают последний подтверждённый успех, а не обязательно фактически работающий контейнер. Смотрите логи и состояние Compose с конфигурацией неудачного release. Откат приложения допустим только после проверки совместимости с текущей схемой БД.

Каталоги releases и локальные Docker-образы автоматически не удаляются. Бэкапы, мониторинг, zero-downtime, автоматическое восстановление и обновление самого VPS не настроены.