deploy/ contains application startup and maintenance tools. The main entry point is deploy/control, without a dot before deploy. Use it for ordinary commands; internal scripts do not need to be run manually.
Project files
| Path | Purpose | Maintained by |
|---|---|---|
deploy/control |
Parses commands, selects the environment, and calls the required tools | Generator |
deploy/generated/environments/<имя>.json |
Generator UI profile settings after Generate | Generator |
deploy/custom/environments/<имя>.json |
Your profile additions; initially {} |
You |
deploy/custom/environments/README.md |
Manual override explanation and examples | You; generator creates the initial file |
deploy/environments/<имя>.json |
Optional complete manual configuration; when present, fully replaces UI and custom | Operator |
deploy/generated/examples/ |
Complete setting examples for different modes; not applied on their own | Generator |
deploy/generated/docker/ |
Dockerfiles for backend, admin, and service ops image | Generator |
deploy/generated/compose/ |
Production/prod-local container composition and settings | Generator |
deploy/generated/nginx/ |
Proxy configuration templates | Generator |
deploy/generated/runtime/ |
Command execution scripts | Generator |
deploy/generated/operator/ |
Go configuration, state, reservation, and recovery tools inside the ops image | Generator |
deploy/generated/README.md |
Guide for the specific generated project | Generator |
deploy/docker-compose.yml |
PostgreSQL for ordinary local development | Generator |
deploy/.state/ |
Local controller state and prod-local data | Controller |
deploy/custom/ |
User extensions | You |
When using UI, do not copy configuration into deploy/environments/: that creates a separate source with highest priority. Use the custom file for extra fields. See environment setup.
What internal scripts do
| Runtime file | Purpose |
|---|---|
environment.sh, environment.jq |
Obtain effective configuration from UI/custom or a complete manual file |
build.sh |
Builds images and writes release JSON; creates an archive or publishes to a registry |
local.sh |
Prepares prod-local on your computer |
production.sh |
Manages server operations and file transfer |
host.sh |
Executes and records individual stages on the host |
provisioning.sh |
Creates initial secrets and certificates and prepares the environment |
recovery.sh |
Creates and restores backups |
rotations.sh |
Rotates secrets and database certificates |
reconfigure.sh |
Applies supported delivery and backup changes |
The backend image contains the application, the admin image contains the built interface, and the ops image contains checking, dump, recovery, and maintenance tools; the migrate command in the backend image runs migrations. PostgreSQL, Nginx, and Certbot are used separately. Build builds or obtains these; you need not build each manually.
CI lives outside runtime: GitLab uses .gitlab-ci.yml, .gitlab/admingen.yml, and custom deploy/custom/gitlab.yml; GitHub uses .github/workflows/admingen.yml, with your additional workflows in separate files. See CI.
Build output
build --output release-001.json creates a release description. For source/archive, an adjacent *.images.tar contains Docker images. Keep the two files together. They are not a backup of the database or user-uploaded images. For registry, images live in the registry and JSON references their exact contents.
Persistent data
On a VPS, JSON root sets the data directory, such as /srv/admingen/example_project/production. It is outside the Git checkout. For prod-local, it is deploy/.state/local in your project.
| Path inside root | Contents |
|---|---|
data/postgres/ |
Working database |
data/media/ |
Working images with local storage |
secrets/, pki/ |
Passwords, keys, and certificates |
config/ |
Working and saved source settings; PostgreSQL, Nginx, and registry configuration |
state/current.json, state/previous.json |
Current and previous successfully published releases |
state/operations/, state/reservation.json |
Operation progress and unfinished-operation information |
release.json, releases/ |
Release information |
incoming/, staging/ |
Input files and intermediate operation results, including diagnostic logs |
certbot/ |
HTTPS certificates, Certbot logs, and public ACME challenge directory |
image-archives/ |
Preserved archives of exact source/archive images |
backups/ |
Backups when local backup is selected |
The controller maintains these files. Do not edit state manually or delete .state to retry startup: it contains real data. For errors, use operation recovery; for data copies, backup.
What to keep in Git
Keep the manifest, source code, deploy/control, deploy/generated/**, and required custom files. UI profiles contain ordinary settings, not secrets, and belong to the project. Custom JSON must also contain no passwords.
Do not commit complete manual configurations deploy/environments/**, local state deploy/.state/**, or secrets. Keep build outputs and backups separately from source.
Generate updates generator files and preserves existing custom files. Deleting a profile in UI does not delete its custom file automatically. Neither Generate nor profile deletion stops the server or deletes its data.
When a generator script needs a change, fix the generator template: manual edits inside generated are lost on the next generation.
Docker images and disk space
Differences between backend, admin, ops, PostgreSQL, and base build images are explained in the image guide. See disk cleanup for checking usage and removing old cache and archives. Deleting a Docker image does not delete its *.images.tar archive and does not always reclaim its full displayed size: layers may be shared with other images.