Add manually gated first production bootstrap with fail-closed residue checks
This commit is contained in:
Pigway
+106
-2
@@ -89,8 +89,8 @@ Never upload that journal or a full Docker inspect as a public CI artifact.
|
||||
Pushes to other branches and pull requests never deploy. A manual run defaults
|
||||
to plan, even when automatic deployment is enabled.
|
||||
|
||||
The script intentionally supports updates to an existing healthy deployment,
|
||||
not first-time bootstrap. No real production deployment or rollback drill has
|
||||
The deploy action supports updates to an existing healthy deployment. For first-time
|
||||
creation use the explicit manual bootstrap flow below. No real production deployment or rollback drill has
|
||||
been performed during implementation; those are first-run acceptance steps.
|
||||
|
||||
## Deployment transaction and rollback
|
||||
@@ -167,3 +167,107 @@ FRAME_FLOW_DEPLOY_OWNER=<confirmed failed owner> CD_ACTION=recover python script
|
||||
recovery fails. If the very first attempt stopped before a journal was written,
|
||||
confirm that the original image is still running and healthy before an operator
|
||||
removes the stale lock. Do not delete a live lock or any persistence volume.
|
||||
|
||||
## First-time production bootstrap (explicit manual action)
|
||||
|
||||
The confirmed NAS residue is a `created`, never-started container with dead
|
||||
`/workspace/way/...` bind paths. It is not an adoption/rollback baseline.
|
||||
No migration from those paths is performed. Production Compose remains independently usable.
|
||||
|
||||
Set these repository Actions **Variables** (not Secrets):
|
||||
|
||||
```text
|
||||
PROD_DEPLOY_ENABLED=true
|
||||
PROD_PROJECT=pigway-frame-flow
|
||||
PROD_CONTAINER=pigway-frame-flow
|
||||
PROD_IMAGE_REPO=pigway-frame-flow
|
||||
PROD_DATA_DIR=/volume2/docker/pigway-frame-flow/data
|
||||
PROD_CONFIG_DIR=/volume2/docker/pigway-frame-flow/config
|
||||
PROD_WEB_BIND=192.0.2.10
|
||||
PROD_WEB_PORT=18787
|
||||
PROD_STATE_VOLUME=pigway-frame-flow-cd-state
|
||||
PROD_MOCK=true
|
||||
PROD_WRITE_ENABLED=false
|
||||
```
|
||||
|
||||
Leave `PROD_PHOTOS_DIR` unset/empty. Existing mirror Variables still apply.
|
||||
Enabling CD does not enable real frame writes. Before the first successful bootstrap,
|
||||
ordinary main pushes report `production not bootstrapped / bootstrap required`.
|
||||
They cannot create production. `bootstrap` additionally requires the Actions event
|
||||
`workflow_dispatch`; the default action remains `plan`. Every action is gated by
|
||||
successful complete Verify on main.
|
||||
|
||||
Create repository Actions **Secret** `PRODUCTION_ENV` as multiline bare `KEY=value`:
|
||||
|
||||
```dotenv
|
||||
FRAME_FLOW_TOKEN=replace-with-a-long-random-private-token
|
||||
KOKONNA_API_KEY=
|
||||
```
|
||||
|
||||
Do not add shell quotes, `export`, interpolation or spaces around `=`. An existing
|
||||
KoKonna key may be supplied but first bootstrap forcibly uses Mock with writes off.
|
||||
Optional application secrets/settings may be added in the same format; bootstrap
|
||||
always overrides Mock/write flags, data/config paths, timezone and build identity.
|
||||
This token remains useful for API/smoke checks even if Web UI uses account login.
|
||||
Do not paste the real Secret into logs or repository files.
|
||||
|
||||
### Safety and cleanup
|
||||
|
||||
Bootstrap builds the verified main revision first, then acquires the same atomic
|
||||
Docker daemon deployment lock used by deploy. Host path checks run in a short-lived,
|
||||
network-disabled helper with **read-only** NAS root mounted, not CI workspace paths.
|
||||
Only explicitly configured data/config directories are subsequently mounted writable
|
||||
for initialization, owned `10333:10333`, mode `0750`. Nonempty directories, symlinks
|
||||
(including ancestor symlinks), overlapping paths and unknown journal resources fail closed.
|
||||
Docker may create missing ancestor directories while creating these exact bind sources;
|
||||
there is no recursive chmod/chown/delete on their parents.
|
||||
|
||||
A same-name residue can be removed **without force** only after checking all of:
|
||||
Compose project/service labels; `Status=created`; `Running=false`;
|
||||
`StartedAt=0001-01-01T00:00:00Z`; exactly two bind mounts `/data` and `/config`;
|
||||
and both old host sources absent. A running, previously started, unknown or data-bearing
|
||||
container is refused. An existing default network must be owned by this Compose
|
||||
project and contain no endpoints other than the validated residue.
|
||||
|
||||
The production service uses `create_host_path=false`, the explicit NAS LAN bind,
|
||||
non-root UID, `unless-stopped`, normal bridge network and existing resource/security
|
||||
limits. Acceptance runs ready, all read-only smoke endpoints, version/commit,
|
||||
preflight mount/port/project/user/restart checks, one restart, repeated checks,
|
||||
Docker health and exact built-image ID before `BOOTSTRAP VERIFIED`.
|
||||
|
||||
On failure after transaction preparation, cleanup removes only this transaction's
|
||||
owner-labelled new container and its newly created, empty, project-labelled network.
|
||||
The previously validated never-started residue has no rollback value and is not recreated.
|
||||
**Data/config files, images/build cache and the private CD journal volume are retained.**
|
||||
No `down -v`, volume prune or removal of unrelated/CI resources is used.
|
||||
Cleanup failure retains the lock so the always recovery step can retry using the journal.
|
||||
A failed bootstrap journal prevents automatic retry: review preserved data and diagnostics
|
||||
before another bootstrap; do not automatically empty those directories or delete the journal.
|
||||
Abrupt host/runner loss still requires operator review of the lock/journal.
|
||||
The journal is private (0700/0600) and may contain prior/candidate secrets; never export it
|
||||
as an Actions artifact. First bootstrap has no prior healthy version to roll back to.
|
||||
|
||||
### First run and acceptance
|
||||
|
||||
1. In Gitea repository **Actions → Verify Frame Flow → Run workflow**, choose branch
|
||||
`main`, action **plan**. This is read-only and reports bootstrap required for the
|
||||
absent/created instance; it is not a bootstrap safety acceptance. Detailed host
|
||||
residue/directory checks happen under the lock in bootstrap.
|
||||
2. Run the same workflow on `main` with action **bootstrap**. Verify runs in full first.
|
||||
No NAS bootstrap is executed merely by committing this implementation.
|
||||
3. Require `BOOTSTRAP VERIFIED` in the deploy log. In Container Manager confirm
|
||||
container `pigway-frame-flow` is running/healthy, user 10333, restart unless-stopped,
|
||||
exact `/volume2/docker/pigway-frame-flow/{data,config}` mounts and
|
||||
`192.0.2.10:18787` binding (not loopback).
|
||||
4. Open `http://192.0.2.10:18787/api/v1/version`; its `commit` must equal the full
|
||||
workflow checkout commit. Check `/ready` returns HTTP 200. The immutable image tag
|
||||
is `pigway-frame-flow:release-<commit>-<transaction>`; compare its image ID in
|
||||
Container Manager with the running container.
|
||||
5. Keep `PROD_DEPLOY_ENABLED=true`. Subsequent main pushes Verify then deploy using
|
||||
this same runtime and journal mechanism. The first update records bootstrap as
|
||||
its rollback baseline. Repeating bootstrap against this instance is refused.
|
||||
Enable real-device read-only access and write access only through separate explicit
|
||||
operator decisions; no automatic change is made by bootstrap.
|
||||
|
||||
Docker tests are mocked locally. The first manual NAS Runner bootstrap, including
|
||||
real host mounts and restart, remains the required live acceptance.
|
||||
|
||||
Reference in New Issue
Block a user