deploy/ содержит инструменты запуска и обслуживания приложения. Основная точка входа — deploy/control, без точки перед deploy. В обычной работе команды вызывают через него; внутренние скрипты вручную запускать не нужно.
Файлы в проекте
| Путь | Назначение | Кто изменяет |
|---|---|---|
deploy/control |
Разбирает команду, выбирает окружение и вызывает нужные инструменты | Генератор |
deploy/generated/environments/<имя>.json |
Настройки профиля из Generator UI после Generate | Генератор |
deploy/custom/environments/<имя>.json |
Ваши дополнения к профилю; изначально {} |
Вы |
deploy/custom/environments/README.md |
Объяснение ручных переопределений и примеры | Вы; первый файл создаёт генератор |
deploy/environments/<имя>.json |
Необязательный полный ручной конфиг; если существует, полностью заменяет UI и custom | Оператор |
deploy/generated/examples/ |
Примеры полных настроек для разных режимов; сами по себе не применяются | Генератор |
deploy/generated/docker/ |
Dockerfile backend, admin и служебного ops-образа | Генератор |
deploy/generated/compose/ |
Состав и настройки production/prod-local контейнеров | Генератор |
deploy/generated/nginx/ |
Шаблоны конфигурации прокси | Генератор |
deploy/generated/runtime/ |
Скрипты выполнения команд | Генератор |
deploy/generated/operator/ |
Go-инструменты проверки конфигурации, состояния, резервирования и восстановления внутри ops-образа | Генератор |
deploy/generated/README.md |
Инструкция для конкретного сгенерированного проекта | Генератор |
deploy/docker-compose.yml |
PostgreSQL для обычной локальной разработки | Генератор |
deploy/.state/ |
Локальное состояние контроллера и данные prod-local | Контроллер |
deploy/custom/ |
Пользовательские расширения | Вы |
При работе через UI не копируйте конфиг в deploy/environments/: это создаст отдельный источник настроек с высшим приоритетом. Нужны дополнительные поля — используйте custom-файл. Подробности — настройка окружения.
Что делают внутренние скрипты
| Файл в runtime | Назначение |
|---|---|
environment.sh, environment.jq |
Получают итоговую конфигурацию из UI/custom либо полного ручного файла |
build.sh |
Собирает образы и записывает JSON релиза; создаёт архив либо публикует в registry |
local.sh |
Подготавливает prod-local на вашем компьютере |
production.sh |
Управляет серверными операциями и передачей файлов |
host.sh |
Выполняет и записывает отдельные этапы на хосте |
provisioning.sh |
Создаёт начальные секреты и сертификаты, готовит окружение |
recovery.sh |
Создаёт и восстанавливает резервные копии |
rotations.sh |
Меняет секреты и сертификаты БД |
reconfigure.sh |
Применяет поддерживаемые изменения доставки и backup |
Backend-образ содержит приложение, admin-образ — собранный интерфейс, ops-образ — инструменты проверки, дампа, восстановления и обслуживания; миграции выполняет команда migrate из backend-образа. Отдельно используются PostgreSQL, Nginx и Certbot. Их собирает или получает build; вручную собирать каждый не требуется.
CI находится вне runtime: GitLab использует .gitlab-ci.yml, .gitlab/admingen.yml и custom deploy/custom/gitlab.yml; GitHub — .github/workflows/admingen.yml, а ваши дополнительные workflows лежат отдельными файлами. Подробнее — CI.
Результат сборки
build --output release-001.json создаёт описание выпуска. Для source/archive рядом появляется *.images.tar с Docker-образами. Храните эти два файла вместе. Это не копия БД и загруженных пользователями изображений. При registry сами образы находятся в registry, а JSON ссылается на их точное содержимое.
Постоянные данные
На VPS каталог данных задаёт root в JSON, например /srv/admingen/example_project/production. Он находится вне Git checkout. Для prod-local это deploy/.state/local в вашем проекте.
| Путь внутри root | Что хранится |
|---|---|
data/postgres/ |
Рабочая БД |
data/media/ |
Рабочие изображения при local storage |
secrets/, pki/ |
Пароли, ключи и сертификаты |
config/ |
Рабочие и сохранённые исходные настройки, конфигурация PostgreSQL, Nginx и registry |
state/current.json, state/previous.json |
Текущий и предыдущий успешно опубликованные релизы |
state/operations/, state/reservation.json |
Ход операций и сведения о незавершённой операции |
release.json, releases/ |
Сведения о релизах |
incoming/, staging/ |
Входные файлы и промежуточные результаты операций, включая диагностические логи |
certbot/ |
HTTPS-сертификаты, журналы Certbot и публичная папка ACME-проверок |
image-archives/ |
Сохранённые архивы точных образов source/archive |
backups/ |
Резервные копии, если выбран local backup |
Эти файлы обслуживает контроллер. Не редактируйте state вручную и не удаляйте .state ради повторного запуска: там находятся реальные данные. Для ошибки используйте восстановление операции, для копии данных — backup.
Что сохранять в Git
Сохраняйте manifest, исходники, deploy/control, deploy/generated/** и нужные custom-файлы. Профили UI содержат обычные настройки, не секреты, и входят в проект. Custom JSON тоже не должен содержать пароли.
Полные ручные конфиги deploy/environments/**, локальное состояние deploy/.state/** и секреты в Git не добавляйте. Результаты сборки и резервные копии храните отдельно от исходников.
Generate обновляет генераторные файлы и сохраняет существующие custom-файлы. Если удалить профиль в UI, его custom-файл сам не удалится. Ни Generate, ни удаление профиля не останавливает сервер и не удаляет его данные.
Если меняется генераторный скрипт, исправление нужно вносить в шаблон генератора: ручная правка внутри generated пропадёт при следующей генерации.
Docker-образы и место на диске
Разница между backend, admin, ops, PostgreSQL и базовыми образами сборки объяснена в руководстве по образам. Как проверить расход места и удалить старый кэш и архивы — в очистке диска. Удаление Docker-образа не удаляет архив *.images.tar и не всегда освобождает его полный отображаемый размер: слои могут использоваться другими образами.