diff --git a/development/vscode-example/settings.json b/development/vscode-example/settings.json index a60982e0..1490b727 100644 --- a/development/vscode-example/settings.json +++ b/development/vscode-example/settings.json @@ -1,7 +1,3 @@ { - "python.defaultInterpreterPath": "${workspaceFolder}/frappe-bench/env/bin/python", - "editor.detectIndentation": false, - "files.eol": "\n", - "files.insertFinalNewline": true, - "files.trimTrailingWhitespace": true + "python.defaultInterpreterPath": "${workspaceFolder}/frappe-bench/env/bin/python" } diff --git a/scripts/easy-docker/docs/development-team-process.md b/scripts/easy-docker/docs/development-team-process.md deleted file mode 100644 index af32c4bd..00000000 --- a/scripts/easy-docker/docs/development-team-process.md +++ /dev/null @@ -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: -- - - - -Verification: -- pre-commit: -- manual matrix: -``` diff --git a/scripts/easy-docker/docs/single-stack-readiness.md b/scripts/easy-docker/docs/single-stack-readiness.md deleted file mode 100644 index 6b5c1fce..00000000 --- a/scripts/easy-docker/docs/single-stack-readiness.md +++ /dev/null @@ -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 ` -- 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` diff --git a/scripts/easy-docker/docs/wizard-flow-clean.md b/scripts/easy-docker/docs/wizard-flow-clean.md deleted file mode 100644 index 1060fd1c..00000000 --- a/scripts/easy-docker/docs/wizard-flow-clean.md +++ /dev/null @@ -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. diff --git a/scripts/easy-docker/docs/wizard-flow.md b/scripts/easy-docker/docs/wizard-flow.md deleted file mode 100644 index 12f3bd52..00000000 --- a/scripts/easy-docker/docs/wizard-flow.md +++ /dev/null @@ -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.