epistemophiliac/frappe_docker
1
0
Fork 0
mirror of https://github.com/frappe/frappe_docker.git synced 2026-06-22 07:45:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

chore(easy-docker): remove branch-local docs artifacts

Browse source
This commit is contained in:
RocketQuack 2026-04-02 15:48:57 +02:00
parent 8d9b855ff4
commit 6833b4be77
5 changed files with 1 additions and 519 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
development/vscode-example/settings.json
View file

@ -1,7 +1,3 @@
{ {
"python.defaultInterpreterPath": "${workspaceFolder}/frappe-bench/env/bin/python", "python.defaultInterpreterPath": "${workspaceFolder}/frappe-bench/env/bin/python"
"editor.detectIndentation": false,
"files.eol": "\n",
"files.insertFinalNewline": true,
"files.trimTrailingWhitespace": true
} }

128
scripts/easy-docker/docs/development-team-process.md
View file

@ -1,128 +0,0 @@
# Easy-Docker Development Team Process
## Purpose
This document defines the working model for the easy-docker team.
Focus is process, responsibilities, and execution flow for ongoing refactoring and feature work.
## Team Setup
- Lead Developer
- Owns scope, priorities, and release decisions.
- Resolves conflicts between technical proposals.
- Approves final merge readiness.
- Senior Developer A (Correctness)
- Reviews control flow, edge cases, and failure behavior.
- Validates data handling, state transitions, and rollback paths.
- Checks defensive programming and explicit error handling.
- Senior Developer B (Architecture)
- Reviews modularity, coupling, and naming consistency.
- Drives DRY/KISS refactors and shared helper extraction.
- Validates maintainability and testability.
- Implementation Developer
- Delivers code changes according to approved scope.
- Keeps behavior stable unless change is explicitly requested.
- Adds/update docs for structure and flow changes.
- QA/Verification Owner
- Runs pre-commit and targeted checks.
- Executes reproducible manual test matrix for wizard paths.
- Reports pass/fail with concrete reproduction steps.
## Working Agreement
- No hidden behavior changes during refactors.
- Source-of-truth decisions must be explicit and documented.
- New code must prefer existing helpers over duplicated logic.
- Every change batch must be reviewable by concern (flow, env, compose, ui).
## Daily Process (Tomorrow Plan)
1. Kickoff (15 min)
- Confirm target scope for the day.
- Confirm "no functional change" boundaries.
- Assign owners for implementation and verification.
2. Design sync (20 min)
- Compare at least two technical options for non-trivial edits.
- Select one approach with short tradeoff note.
3. Implementation blocks
- Work in small vertical batches (one concern per batch).
- Keep public function contracts stable where possible.
- Update docs in the same batch when structure changes.
4. Review blocks
- Senior A reviews correctness and failure paths.
- Senior B reviews architecture and maintainability.
- Lead resolves conflicts and accepts/rejects batch.
5. Verification block
- Run pre-commit for changed files.
- Run targeted manual flow checks.
- Record results in short checklist format.
6. Handover
- Write what is done, what is pending, and next first task.
- List any blockers with owner and proposed resolution.
## Implementation Workflow
1. Define scope and constraints.
2. Map affected files/functions.
3. Propose options and select approach.
4. Implement with small commits by concern.
5. Validate with checks and manual path coverage.
6. Document final state and next steps.
## Review Workflow
1. Findings-first review format.
2. Severity order: BLOCKER, HIGH, MEDIUM, LOW.
3. Each point must include file reference and reason.
4. Lead decision:
- Approved
- Approved with conditions
- Not approved
## Test and Verification Matrix (Minimum)
- Create new production stack and complete wizard.
- Create new development stack and complete wizard.
- Manage existing stack:
- Apps -> Generate apps.json
- Apps -> Select apps and branches
- Docker -> Generate docker compose from env
- Docker -> Start stack in Docker Compose (single-host topology)
- Abort/Back paths:
- Back navigation in each submenu
- Abort wizard with rollback
- Validation paths:
- Domain validation error then correction
- Branch selection from apps catalog (including back-navigation)
## Definition of Done (Team)
- Scope completed with no unplanned behavior change.
- No avoidable duplication introduced.
- Review completed by both senior roles.
- Lead verdict documented.
- Verification evidence recorded.
- Handover notes prepared for next workday.
## Handover Template
Use this at day end:
```text
Date:
Completed:
- ...
In Progress:
- ...
Next First Task:
- ...
Blockers:
- <owner> - <issue> - <proposed action>
Verification:
- pre-commit: <pass/fail + note>
- manual matrix: <pass/fail + note>
```

174
scripts/easy-docker/docs/single-stack-readiness.md
View file

@ -1,174 +0,0 @@
# 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`

76
scripts/easy-docker/docs/wizard-flow-clean.md
View file

@ -1,76 +0,0 @@
# Easy Docker Wizard Flow (Clean View)
This document shows the wizard paths in a clean, forward-only view.
Back/Cancel/Exit loops are intentionally hidden to keep the flow readable.
## 1) Main Wizard Paths
```mermaid
flowchart TD
A[Main Menu]
A --> B[Production Setup]
A --> C[Development Setup]
A --> D[Environment Check]
A --> Z[Exit]
B --> E[Create new stack]
B --> F[Manage existing stacks]
C --> E2[Create new stack]
C --> F2[Manage existing stacks]
E --> G[Create stack dir + metadata.json]
E2 --> G
G --> H[Topology selection]
H --> I[Single-host flow]
H --> J[Split services flow]
I --> K[Persist files + render compose]
K --> L[Done]
J --> J2[Current status: placeholder only]
J2 --> L2[Pending implementation]
F --> M[Select existing stack]
F2 --> M
M --> N[Manage stack actions]
N --> N1[Apps actions]
N --> N2[Docker actions]
N1 --> O[apps.json generated/updated]
N2 --> P[compose.generated.yaml rendered]
N2 --> Q[Start stack in Docker Compose]
Q --> Q1{Topology}
Q1 -->|single-host| Q2[docker compose up -d]
Q1 -->|split-services / others| Q3[Show runbook warning]
```
## 2) Single-host Detail Path
```mermaid
flowchart TD
S1[Single-host selected]
S1 --> S2[Choose proxy mode]
S2 --> S3[Choose database mode]
S3 --> S4[Choose redis mode]
S4 --> S5[Set CUSTOM_IMAGE + CUSTOM_TAG]
S5 --> S6[Select apps: apps catalog]
S6 --> S7[For each selected app: fetch branches + choose branch]
S7 --> S8[Proxy-specific questions]
S8 --> S9[Database-specific questions]
S9 --> S10[Write .env]
S10 --> S11[Write metadata.json]
S11 --> S12[Generate apps.json]
S12 --> S13[Render compose.generated.yaml]
S13 --> S14[Success message]
```
## 3) Notes
- This is a readability-focused flow map, not an exhaustive state machine.
- Navigation loops (Back/Cancel/Exit) are intentionally omitted.
- `Split services` remains not fully implemented in the wizard runtime.
- `Start stack in Docker Compose` currently supports only `single-host` topology.
- Site bootstrap is currently scoped to one supported site per stack.
- The site bootstrap installs the full app selection stored on the stack.
- Multiple sites in one stack with different per-site app selections are
not supported yet and are planned for a later phase.

136
scripts/easy-docker/docs/wizard-flow.md
View file

@ -1,136 +0,0 @@
# Easy Docker Wizard Flow
```mermaid
flowchart TD
A[Main Menu] -->|Production Stack| B[Setup Menu: Production]
A -->|Development Stack| C[Setup Menu: Development]
A -->|Environment check| D[Environment Status]
A -->|Exit| Z1[Exit App]
D -->|Back to main menu| A
D -->|Exit and close easy-docker| Z1
B -->|Create new stack| E[Prompt: Stack name]
B -->|Manage existing stacks| F[List existing production stacks]
B -->|Back| A
B -->|Exit| Z1
C -->|Create new stack| E2[Prompt: Stack name]
C -->|Manage existing stacks| F2[List existing development stacks]
C -->|Back| A
C -->|Exit| Z1
E --> E3[Select Frappe branch profile from frappe.tsv]
E2 --> E4[Select Frappe branch profile from frappe.tsv]
E3 --> G[Create stack directory + metadata.json]
E4 --> G2[Create stack directory + metadata.json]
G --> H[Topology Menu]
G2 --> H2[Topology Menu]
H -->|Single-host| I[Single-host selection]
H -->|Split services| J[Split services example]
H -->|Abort wizard to main menu| K[Abort prompt]
H -->|Back/Cancel| B
H2 -->|Single-host| I
H2 -->|Split services| J
H2 -->|Abort wizard to main menu| K
H2 -->|Back/Cancel| C
J -->|Use this topology| J2[Info: placeholder path]
J -->|Back| H
J2 --> H
K -->|Rollback files and return to main menu| A
K -->|Keep files and return to main menu| A
K -->|Back to topology selection| H
I --> I1[Proxy mode]
I1 --> I2[Database mode]
I2 --> I3[Redis mode]
I3 --> I6[Prompt CUSTOM_IMAGE + CUSTOM_TAG]
I6 --> I7[App selection list]
I7 -->|Enter| I8[Per selected app: choose branch from apps.tsv]
I8 --> I9[Continue]
I9 --> P{Proxy specific questions}
P -->|traefik-https| P1[SITE_DOMAINS + LETSENCRYPT_EMAIL + HTTP_PUBLISH_PORT? + HTTPS_PUBLISH_PORT?]
P -->|nginxproxy-https| P2[SITE_DOMAINS + NGINX_PROXY_HOSTS + LETSENCRYPT_EMAIL + HTTP_PUBLISH_PORT? + HTTPS_PUBLISH_PORT?]
P -->|nginxproxy-http| P3[SITE_DOMAINS + NGINX_PROXY_HOSTS + HTTP_PUBLISH_PORT?]
P -->|traefik-http| P4[HTTP_PUBLISH_PORT?]
P -->|caddy-external / no-proxy| P5[HTTP_PUBLISH_PORT? default 8080]
P1 --> DBQ
P2 --> DBQ
P3 --> DBQ
P4 --> DBQ
P5 --> DBQ
DBQ{Database specific question}
DBQ -->|postgres| DB1[DB_PASSWORD required]
DBQ -->|mariadb| DB2[DB_PASSWORD optional]
DB1 --> S[Write stack env file]
DB2 --> S
S --> T[Write metadata.json with top-level apps]
T --> U[Generate apps.json from metadata.json apps]
U --> V[Render compose.generated.yaml from metadata + env]
V --> W[Success message]
W --> B
F -->|Stack selected| M[Manage selected stack]
F -->|Back| B
F -->|Exit| Z1
F -->|No stacks found| F0[Manage stacks placeholder]
F0 -->|Back| B
F0 -->|Exit| Z1
F2 -->|Stack selected| M
F2 -->|Back| C
F2 -->|Exit| Z1
F2 -->|No stacks found| F20[Manage stacks placeholder]
F20 -->|Back| C
F20 -->|Exit| Z1
M --> M2[Stack actions: Apps / Docker / Back / Exit]
M2 -->|Apps| M3[Apps submenu]
M2 -->|Docker| M4[Docker submenu]
M2 -->|Back| M0[Return to current stack list]
M2 -->|Exit| Z1
M0 --> F
M0 --> F2
M3 -->|Generate apps.json| M31[Read metadata.json apps + regenerate apps.json]
M3 -->|Select apps and branches| M32[Re-prompt app and branch selection]
M32 --> M33[Update metadata.json apps]
M33 --> M34[Regenerate apps.json from metadata]
M34 --> M3
M3 -->|Back| M2
M3 -->|Exit| Z1
M31 --> M3
M4 -->|Generate docker compose from env| M41[Render compose.generated.yaml]
M4 -->|Start stack in Docker Compose| M42[Topology gate]
M42 -->|single-host| M43[docker compose up -d]
M42 -->|split-services / others| M44[Show topology-specific runbook message]
M4 -->|Back| M2
M4 -->|Exit| Z1
M41 --> M4
M43 --> M4
M44 --> M4
```
## Notes
- `SITE_DOMAINS` validation accepts only domain names in form `sub.domain.tld` or `sub.sub.domain.tld`.
- Existing stack lists are filtered by `setup_type` (`production` vs `development`).
- In `Manage existing stacks`, navigation options are only `Back` and `Exit`.
- `Select apps and branches` writes app selection to top-level `apps` in `metadata.json`.
- `Generate apps.json` uses only `metadata.json -> apps` as source of truth.
- New stack wizard always uses custom image path (no separate official-vs-custom image step).
- `Start stack in Docker Compose` is currently allowed only for `single-host` topology stacks.
## Module Layout
- `lib/app/wizard/common.sh` is now a loader for common modules under `lib/app/wizard/common/`.
- `lib/app/wizard/env.sh` is now a loader for env modules under `lib/app/wizard/env/`.
- `lib/app/wizard/flows.sh` is now a loader for flow modules under `lib/app/wizard/flows/`.
- Public function names and flow behavior remain unchanged; only code organization was refactored.