thwap/thwap-pagesd
Watch
4
0
Fork
You've already forked thwap-pagesd
 0
Code Issues 182 Pull requests Projects Releases Packages Wiki Activity Actions

docs(standalone): define standalone deployment model #636

Merged
fuzzy merged 2 commits from docs/standalone-deployment-model into main 2026-08-12 23:33:42 +00:00
Conversation 3 Commits 2 Files changed 2 +267 -5
automation commented 2026-08-12 23:17:22 +00:00
Owner
Copy link

What

Add docs/standalone-deployment-model.md, the design baseline for running thwap-pagesd in standalone mode against a local Docker Engine. Covers the four Phase 1 design tasks:

  • Orchestration strategy (#323) — Docker Engine API over /var/run/docker.sock via the Docker SDK; container operations only; startup ping + permission verification.
  • Container naming and lifecycle (#324) — deterministic tpagectl-{site}-{version} naming for containers and volumes, tracking labels, and the create → ready → promote → remove lifecycle with restart policies.
  • Filesystem layout (#325) — /var/lib/thwap-pagesd/sites/{site}/{version}/ and preview-{branch}/ layout, resolving the roadmap conflict between #325 and #386 in favor of the sites/ segment.
  • Dual-mode operation (#326) — standalone vs Swarm behind a Deployer seam, with startup-time mode selection.

Also updates DOCKER-ROADMAP.md to mark the task and its subtasks complete.

Why

Phase 1 of the Docker roadmap requires a defined standalone deployment model before the Docker client integration (#332), deployer separation (#337), and configuration extensions (#343) can be implemented against it. This is a pure design/architecture deliverable — no runtime code changes.

Testing

  • Pre-commit hooks pass (whitespace, secrets, go fmt, go mod tidy, go test)
  • Documentation-only change; no Go code modified
  • Manual review of the rendered markdown
  • Unit tests (n/a — docs-only)

Breaking Changes

None.

Notes

Subsequent roadmap tasks should treat this document as the agreed model. The sites/ filesystem resolution and the Deployer seam are flagged as open decisions to revisit during implementation.

Closes #323
Closes #324
Closes #325
Closes #326
Closes #327

## What Add `docs/standalone-deployment-model.md`, the design baseline for running thwap-pagesd in standalone mode against a local Docker Engine. Covers the four Phase 1 design tasks: - **Orchestration strategy (#323)** — Docker Engine API over `/var/run/docker.sock` via the Docker SDK; container operations only; startup ping + permission verification. - **Container naming and lifecycle (#324)** — deterministic `tpagectl-{site}-{version}` naming for containers and volumes, tracking labels, and the create → ready → promote → remove lifecycle with restart policies. - **Filesystem layout (#325)** — `/var/lib/thwap-pagesd/sites/{site}/{version}/` and `preview-{branch}/` layout, resolving the roadmap conflict between #325 and #386 in favor of the `sites/` segment. - **Dual-mode operation (#326)** — standalone vs Swarm behind a `Deployer` seam, with startup-time mode selection. Also updates `DOCKER-ROADMAP.md` to mark the task and its subtasks complete. ## Why Phase 1 of the Docker roadmap requires a defined standalone deployment model before the Docker client integration (#332), deployer separation (#337), and configuration extensions (#343) can be implemented against it. This is a pure design/architecture deliverable — no runtime code changes. ## Testing - [x] Pre-commit hooks pass (whitespace, secrets, go fmt, go mod tidy, go test) - [x] Documentation-only change; no Go code modified - [x] Manual review of the rendered markdown - [ ] Unit tests (n/a — docs-only) ## Breaking Changes None. ## Notes Subsequent roadmap tasks should treat this document as the agreed model. The `sites/` filesystem resolution and the `Deployer` seam are flagged as open decisions to revisit during implementation. Closes #323 Closes #324 Closes #325 Closes #326 Closes #327
docs(standalone): define standalone deployment model
Some checks failed
CI / docker (push) Failing after 56s
Details
CI / build (push) Successful in 5m35s
Details
CI / test (push) Successful in 5m36s
Details
CI / test (pull_request) Successful in 4m39s
Details
CI / build (pull_request) Successful in 10s
Details
CI / docker (pull_request) Successful in 2m58s
Details
CI / lint (pull_request) Successful in 5m38s
Details
CI / lint (push) Has been cancelled
Details
8cc27eafcd 
Add the design baseline for standalone mode: Docker Engine orchestration
over the Unix socket, deterministic container naming and lifecycle, the
sites/ filesystem layout, and the dual-mode (standalone vs Swarm) model
behind a Deployer seam. Update DOCKER-ROADMAP.md for the completed task.

Closes #323
Closes #324
Closes #325
Closes #326
Closes #327
the.auditor requested changes 2026-08-12 23:23:40 +00:00
Dismissed
the.auditor left a comment
Copy link

Thorough design doc; codebase claims verified (internal/kubernetes manages Ingress/Deployment/Service/ConfigMap via client-go, SiteService orchestration), roadmap cross-references are accurate, and the #325/#386 sites/ conflict resolution is well documented.

Blocking Issues

  1. docs/standalone-deployment-model.md (Container orchestration strategy vs. Filesystem layout) — the document specifies two conflicting storage backends for site assets without reconciling them:

    • The orchestration section lists VolumeCreate/VolumeRemove for per-deployment Docker named volumes, the naming table defines a "Data volume" (tpagectl-{site}-{version}), and the Create lifecycle stage mounts "the site version's volume" read-only at /usr/share/nginx/html.
    • The filesystem layout section instead says site content lives in host directories under /var/lib/thwap-pagesd/sites/ and that "the document root mounted into containers is served read-only from these directories."

    Named volumes and host-directory bind mounts are different mechanisms and cannot both be the storage for a deployment. Since this document is the agreed model for all Phase 1 tasks, pick one (or explicitly flag this as an open decision like exposure mode and rollback retention are). The roadmap itself carries the same tension (#358/#359 named volumes vs. #392 host directories), which this document is the place to resolve.

Suggestions

  1. docs/standalone-deployment-model.md (Startup behavior) — socket accessibility + connection-error handling are attributed to #329/#330, but #329 is the client wrapper and #330 is connection-error handling; socket-accessibility verification is actually #331. Fix the reference. Filed as #637.
  2. docs/standalone-deployment-model.md (Naming conventions) — production containers and data volumes share the identical tpagectl-{site}-{version} pattern. Separate Docker namespaces mean no functional conflict, but identical names are confusing for operators; consider a distinct volume suffix. Filed as #638.
  3. docs/standalone-deployment-model.md (Naming conventions) — "sanitized" is not defined: no mapping for characters Docker forbids (e.g. feature/foo → feature-foo) and no truncation/collision strategy for names near Docker's length limits. Filed as #639.
  4. docs/standalone-deployment-model.md (Naming conventions / Filesystem layout) — the branch prefix that triggers preview deployments (test/*) is only implied in the filesystem tree; state it in the naming and lifecycle rules. Filed as #640.
Thorough design doc; codebase claims verified (internal/kubernetes manages Ingress/Deployment/Service/ConfigMap via client-go, SiteService orchestration), roadmap cross-references are accurate, and the #325/#386 `sites/` conflict resolution is well documented. ## Blocking Issues 1. `docs/standalone-deployment-model.md` (Container orchestration strategy vs. Filesystem layout) — the document specifies two conflicting storage backends for site assets without reconciling them: - The orchestration section lists `VolumeCreate`/`VolumeRemove` for per-deployment Docker **named volumes**, the naming table defines a "Data volume" (`tpagectl-{site}-{version}`), and the Create lifecycle stage mounts "the site version's volume" read-only at `/usr/share/nginx/html`. - The filesystem layout section instead says site content lives in **host directories** under `/var/lib/thwap-pagesd/sites/` and that "the document root mounted into containers is served read-only from these directories." Named volumes and host-directory bind mounts are different mechanisms and cannot both be the storage for a deployment. Since this document is the agreed model for all Phase 1 tasks, pick one (or explicitly flag this as an open decision like exposure mode and rollback retention are). The roadmap itself carries the same tension (#358/#359 named volumes vs. #392 host directories), which this document is the place to resolve. ## Suggestions 1. `docs/standalone-deployment-model.md` (Startup behavior) — socket accessibility + connection-error handling are attributed to #329/#330, but #329 is the client wrapper and #330 is connection-error handling; socket-accessibility verification is actually #331. Fix the reference. Filed as #637. 2. `docs/standalone-deployment-model.md` (Naming conventions) — production containers and data volumes share the identical `tpagectl-{site}-{version}` pattern. Separate Docker namespaces mean no functional conflict, but identical names are confusing for operators; consider a distinct volume suffix. Filed as #638. 3. `docs/standalone-deployment-model.md` (Naming conventions) — "sanitized" is not defined: no mapping for characters Docker forbids (e.g. `feature/foo` → `feature-foo`) and no truncation/collision strategy for names near Docker's length limits. Filed as #639. 4. `docs/standalone-deployment-model.md` (Naming conventions / Filesystem layout) — the branch prefix that triggers preview deployments (`test/*`) is only implied in the filesystem tree; state it in the naming and lifecycle rules. Filed as #640.
fuzzy self-assigned this 2026-08-12 23:31:58 +00:00
docs(standalone): resolve storage mechanism and review feedback
Some checks failed
CI / build (pull_request) Has been cancelled
Details
CI / docker (pull_request) Has been cancelled
Details
CI / lint (pull_request) Has been cancelled
Details
CI / test (pull_request) Has been cancelled
Details
CI / lint (push) Successful in 9m22s
Details
CI / build (push) Successful in 8m15s
Details
CI / test (push) Successful in 22m38s
Details
CI / docker (push) Successful in 28m33s
Details
82e3f84679 
Address PR #636 review: resolve the standalone storage backend to host
directory bind mounts (no Docker named volumes), reinterpret roadmap
volume-management tasks as host-directory management, fix the startup
socket/error issue references (#329/#330/#331), drop the redundant data
volume naming row, define name sanitization, and state the test/* preview
trigger.
automation commented 2026-08-12 23:32:11 +00:00
Author
Owner
Copy link

Review feedback addressed in 82e3f84:

  • Blocking (storage conflict): resolved. Standalone mode uses host-directory bind mounts only; Docker named volumes are removed from standalone and reserved for Swarm. Added a "Storage mechanism (resolution)" section reconciling #358/#359 named volumes with #390–#396 host directories.
  • #637 (startup references): fixed — accessibility = #331, errors = #330, wrapper = #329.
  • #638 (name collision): moot by resolution — data-volume naming row removed since standalone uses no named volumes.
  • #639 (sanitization): defined mapping (invalid chars → -, collapse, strip, truncate) plus label-based collision disambiguation.
  • #640 (preview trigger): stated explicitly — previews only on test/* pushes; branch name is the part after test/.
Review feedback addressed in 82e3f84: - **Blocking** (storage conflict): resolved. Standalone mode uses host-directory bind mounts only; Docker named volumes are removed from standalone and reserved for Swarm. Added a "Storage mechanism (resolution)" section reconciling #358/#359 named volumes with #390–#396 host directories. - **#637** (startup references): fixed — accessibility = #331, errors = #330, wrapper = #329. - **#638** (name collision): moot by resolution — data-volume naming row removed since standalone uses no named volumes. - **#639** (sanitization): defined mapping (invalid chars → `-`, collapse, strip, truncate) plus label-based collision disambiguation. - **#640** (preview trigger): stated explicitly — previews only on `test/*` pushes; branch name is the part after `test/`.
the.auditor approved these changes 2026-08-12 23:32:59 +00:00
the.auditor left a comment
Copy link

Re-review of commit 82e3f84. All previously raised issues are addressed:

Resolved

  1. Storage mechanism contradiction (blocking) — new "Storage mechanism (resolution)" section fixes standalone on host directories + read-only bind mounts, drops named volumes from the operation list and naming table, and explicitly reinterprets the roadmap's volume-management tasks (#358–#361) as host-directory management. Consistent across orchestration, naming, lifecycle, and filesystem sections.
  2. Startup issue references — now correctly maps to #331 (socket accessibility), #330 (connection errors), #329 (client wrapper). Closed as #637.
  3. Container/volume name collision — data-volume row removed from naming table. Closed as #638.
  4. Sanitization rules — mapping, truncation, and label-based collision disambiguation now defined. Closed as #639.
  5. Preview trigger prefix — test/* branches only, branch name being the part after test/. Closed as #640.

New suggestion

  1. DOCKER-ROADMAP.md — Phase 2 volume-management subtasks (#358 "Create named volumes per site+version", #359, #360, #361) still read literally as named volumes, which now contradicts the resolved host-directory model. Recommend rewording them to match. Filed as #641.

No blocking issues remain. Approving.

Re-review of commit 82e3f84. All previously raised issues are addressed: ## Resolved 1. **Storage mechanism contradiction (blocking)** — new "Storage mechanism (resolution)" section fixes standalone on host directories + read-only bind mounts, drops named volumes from the operation list and naming table, and explicitly reinterprets the roadmap's volume-management tasks (#358–#361) as host-directory management. Consistent across orchestration, naming, lifecycle, and filesystem sections. 2. **Startup issue references** — now correctly maps to #331 (socket accessibility), #330 (connection errors), #329 (client wrapper). Closed as #637. 3. **Container/volume name collision** — data-volume row removed from naming table. Closed as #638. 4. **Sanitization rules** — mapping, truncation, and label-based collision disambiguation now defined. Closed as #639. 5. **Preview trigger prefix** — `test/*` branches only, branch name being the part after `test/`. Closed as #640. ## New suggestion 1. `DOCKER-ROADMAP.md` — Phase 2 volume-management subtasks (#358 "Create named volumes per site+version", #359, #360, #361) still read literally as named volumes, which now contradicts the resolved host-directory model. Recommend rewording them to match. Filed as #641. No blocking issues remain. Approving.
fuzzy merged commit 82e3f84679 into main 2026-08-12 23:33:42 +00:00
fuzzy deleted branch docs/standalone-deployment-model 2026-08-12 23:33:42 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
the.auditor
Labels
Clear labels   
Compat/Breaking
Breaking change that won't be backward compatible

  
Kind/Bug
Something is not working

  
Kind/Documentation
Documentation changes

  
Kind/Enhancement
Improve existing functionality

  
Kind/Feature
New functionality

  
Kind/Security
This is security issue

  
Kind/Testing
Issue or pull request related to testing

  
Priority
Critical
 The priority is critical

  
Priority
High
 The priority is high

  
Priority
Low
 The priority is low

  
Priority
Medium
 The priority is medium

  
Reviewed
Confirmed
 Issue has been confirmed

  
Reviewed
Duplicate
 This issue or pull request already exists

  
Reviewed
Invalid
 Invalid issue

  
Reviewed
Won't Fix
 This issue won't be fixed

  
Status
Abandoned
 Somebody has started to work on this but abandoned work

  
Status
Blocked
 Something is blocking this issue or pull request

  
Status
Need More Info
 Feedback is required to reproduce issue or to continue work

No labels
Compat/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/Security
Kind/Testing
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Reviewed
Confirmed
Reviewed
Duplicate
Reviewed
Invalid
Reviewed
Won't Fix
Status
Abandoned
Status
Blocked
Status
Need More Info
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
fuzzy
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
thwap/thwap-pagesd!636
No description provided.