mirror of
https://github.com/frappe/frappe_docker.git
synced 2026-06-17 13:55:08 +00:00
174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
# 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`
|