frappe_docker/scripts/easy-docker/docs/single-stack-readiness.md

Easy-Docker Single-Stack Readiness

Purpose

This document freezes the required single-stack scope for easy-docker before work moves to separate services.

Current interpretation:

• single-stack means the implemented single-host topology.
• The stack must be isolated from other stacks at the Docker Compose project level.
• The supported happy path is one usable site per stack unless a later product decision explicitly broadens this.
• The current site bootstrap path always installs the full app selection stored on the stack itself.
• It is not yet supported to create multiple sites in one stack with different app selections per site.

Current Supported Scope

The current codebase already supports these single-stack paths:

• Create production stack
• Create development stack
• Choose single-host topology
• Select proxy, database, and redis mode
• Select apps and branches
• Persist metadata.json, stack .env, apps.json
• Render compose.generated.yaml
• Manage existing stacks
• Regenerate apps.json
• Re-select apps and branches
• Build custom image
• Start stack with Docker Compose
• Stop stack with Docker Compose
• Show stack runtime status
• Abort wizard with rollback or keep-files behavior
• Isolate stacks through stack-specific Compose project names

Definition Of Done Before Separate Services

Single-stack is not considered complete when containers merely run. It is considered complete when the user can move from stack creation to a usable Frappe/ERPNext site and operate that stack safely.

Minimum user-facing path:

1. Create stack
2. Configure single-host topology
3. Build image if needed
4. Start stack
5. Create/bootstrap first site
6. Install selected apps on that site
7. Verify site access behind the chosen proxy mode
8. Stop/restart/down the stack
9. Re-open manage flow and inspect status/logs

Required Remaining Changes

High Priority

• Add a documented or automated site/bootstrap path
  • create first site
  • install selected apps
  • verify site routing/access
• Freeze the supported site model
  • recommended: one site per stack as the supported happy path

Medium Priority

• Add remaining lifecycle operations
  • restart
  • down/remove
  • logs
• Add post-start recovery guidance
  • partial start
  • failed bootstrap
  • retry after custom image rebuild
• Add one-time cleanup/runbook note for stacks created before per-stack Compose project isolation

Hardening Priority

• Keep runtime status semantics explicit
  • Not created
  • Created
  • Running
  • Partial
  • Stopped
  • Restarting
  • optional uptime hint
• Ensure manage actions only affect the selected stack
• Preserve safe abort/rollback behavior

Required Single-Stack Paths

Setup Paths

• Environment check
• Create production stack
• Create development stack
• Complete single-host wizard
• Back/cancel at each prompt
• Abort wizard with rollback
• Abort wizard while keeping files

Runtime Paths

• Generate compose from env
• Build custom image
• Start stack
• Stop stack
• Restart stack
• Down/remove stack resources
• Inspect runtime status
• Inspect logs

Site Paths

• Create first site
• Install selected apps on the site
• Current limitation: the site install set is the stack app set
  • one stack -> one supported site -> one shared app selection
• Verify the site is reachable
• Re-open and manage the stack after restart

Recovery Paths

• Missing custom image -> build -> retry start
• Invalid app branch -> mapped build failure
• Partial start -> inspect status/logs -> retry
• Failed bootstrap -> rerun or recover cleanly
• Cleanup of pre-isolation shared Compose leftovers

Verification Matrix

Before calling single-stack ready, the team should execute at least:

1. Environment/bootstrap gate
2. New production single-stack creation
3. New development single-stack creation
4. Apps regeneration/update path
5. Compose render path
6. Custom image build success and failure paths
7. Start path including missing-image build/retry
8. Stop path
9. Runtime isolation between two stacks
10. Runtime status in not-created/created/running/partial/stopped states
11. Abort/back/rollback paths
12. Validation error and correction paths
13. Site/bootstrap reality check after stack start

Required automated checks on every single-stack change:

• bash -n on touched shell files
• pre-commit run --files <changed easy-docker files>
• compose render/config validation for at least one production and one development stack

Lead Verdict

single-stack is close on the Compose/runtime side but is not yet fully done.

The largest remaining gap before separate services is the missing site/bootstrap lifecycle. After that, the next most important gaps are restart, down/remove, logs, and reproducible manual verification.

Recommended order:

1. Freeze single-stack site model
2. Add site/bootstrap path
3. Add restart, down/remove, and logs
4. Run the verification matrix
5. Move to separate services