Compose edit & deploy¶
What this is¶
Tools to edit compose (and related files) on a free-form host project, keep version history, validate, and deploy changes — including pull-only checks vs full up -d.
Why it exists¶
Editing compose only over SSH loses history and audit. The editor records versions, can multi-file save, and runs deploy as a job with logs so operators see pull/up failures instead of silent “success.”
For a one-off sidecar or log without opening the project editor, use Host Files (jailed SFTP; flag off by default). Files has the same in-page editor feel (gutter / wrap / Tab) for any UTF-8 file up to 512 KiB. .env in the compose editor is redacted until step-up; Files lists .env but open/edit/download needs the same 2FA grant as privileged Files (no in-editor masking).
End-to-end: small compose change¶
- Docker page → project ⋯ → Quick edit (tiny change) or Full editor… (history / multi-file).
- Edit compose / override /
.envas needed. - Validate YAML if offered.
- Save & Deploy (or deploy action) — wait for job.
- Confirm containers healthy; check Audit for the change actor.
Opening the editor¶
From a project’s ⋯ menu on the Docker page:
| Action | What you get |
|---|---|
| Quick edit | In-page modal (textarea) for compose and optional Dockerfile tab only |
| Full editor… | Dedicated multi-file page: compose, override, .env, sidecars, sets, history, validate YAML |
From Quick edit, use Open full editor → (or the Dockerfile equivalent when that tab is active) to leave the modal for the full page. Quick edit footer notes that .env and other sidecars are full-editor only (not planned for the quick modal).
Desktop
Prefer Full editor… from the ⋯ menu when you need history, drafts, .env, or multi-file tabs. Quick edit is best for small compose-only tweaks.
Multi-file projects¶
On Docker → Full editor, PiHerder loads when present:
docker-compose.yml(or compose.yaml) — primary- override file (
docker-compose.override.yml, …) - Compose set files:
docker-compose.<name>.yml/compose.<name>.yml(discovered in the project directory) .env(created empty on template deploy when the stack has no env keys yet)- Config / sidecar files next to compose (e.g.
promtail-config.yaml) when discovered as host file mounts or present on disk Dockerfile
For template-managed projects, tabs also fill any desired-state files that are not yet on the host (so you can create a missing sidecar from the editor).
Tabs edit each file (file badges in the chrome — compose / env / config); Save & Deploy writes the full set and redeploys. Version history stores multi-file snapshots (merge-on-save so one file no longer wipes the others).
Word wrap: toggle wrap in the editor. Line numbers stay aligned with wrapped lines (gutter heights remeasured after the overlay is forced to the editor size).
On the host, Compose still auto-loads override + .env in the project directory. Extra set files are not auto-merged unless you pass -f (or use PiHerder Deploy \<set> set).
Compose sets vs override¶
| Kind | Example | Docker view | Deploy |
|---|---|---|---|
| Override | docker-compose.override.yml | Part of multi-file editor only | Merged automatically with primary on plain compose up |
| Set | docker-compose.e2e.yml | Sub-view pills under the same project | Optional set-scoped deploy (-f); does not create a second project card |
See Docker overview — Compose sets.
Check updates vs Deploy¶
| Button | Effect |
|---|---|
| Check updates | Pull, then compare each running container with that image. The update flag stays until the running container is the new image. No up -d. Runs as a Job (docker_stack_check) with live log. |
| Deploy | Pull + up -d (default Compose files in the project dir). Job docker_stack_deploy with live log. |
| Deploy \<set> set | Pull + up -d with -f docker-compose.<set>.yml only — still same project path/name. |
| Stop / Start / Restart all | docker compose stop\|start\|restart for the whole project. Jobs docker_stack_stop / _start / _restart with confirm + live log. |
Check, Deploy, and whole-project lifecycle open the job holding modal (same pattern as OS/container patch). Follow progress under Jobs or Audit if you leave the page. Stack mutations (deploy, stop, start, restart, template apply) share one exclusive lane per host; stack check is exclusive with other checks.
Build¶
Build from the Docker project menu streams docker compose build over SSE.
- operator+ only (viewer 403)
- POST to
/servers/{id}/docker/build-streamwith the compose project name — GET and raw filesystem paths are rejected - Remote command paths are
shlex.quoted
New project wizard¶
Creates a project directory under the Docker base dir and optional initial compose.
Template stacks¶
If a project is template-managed, prefer the deployment page for variables, secrets, redeploy, and drift.
| Path | When |
|---|---|
| Template settings… (⋯ or gate modal) | Variables / secrets / Save & redeploy |
| Quick edit / Full editor… | Raw host files — gate modal warns first; menu labels are plain (Quick edit, Full editor…, Edit files) |
| Deployment host file editor (text link) | Same multi-file host editor, linked from the deployment page |
| Accept host as desired | After an intentional host edit you want to keep — clears drift without rewriting the host |
Saving in the host editor writes the host only; it does not update template desired state unless you Accept host as desired (or redeploy from the template package).
Editor load path (implementers)¶
Workspace resolution lives in app/services/compose_editor.py (inventory → fallback path under docker base → live files → template desired sidecars → drafts). Pure file-kind / sidecar helpers: app/services/compose_project_files.py. Host adopt/migrate desired state: app/services/service_templates/host_sync.py.