diff --git a/docs/01-getting-started/05-easy-docker.md b/docs/01-getting-started/05-easy-docker.md new file mode 100644 index 00000000..55d1038c --- /dev/null +++ b/docs/01-getting-started/05-easy-docker.md @@ -0,0 +1,37 @@ +--- +title: Easy Docker +--- + +# Easy Docker + +`easy-docker` is the interactive setup and management workflow for this repository. +It guides common stack operations through a terminal UI so you do not have to assemble +every Docker and Bench command manually. + +For the detailed guide, use the dedicated docs area under `docs/10-easy-docker/`. +This getting-started page stays short and focuses on the first steps. + +Current status: + +- `single-host` is the primary supported topology +- `split-services` is still in development +- stack, site, app, backup, restart, and update flows are being expanded iteratively + +The script entrypoint is: + +```bash +bash easy-docker.sh +``` + +Minimal first use: + +1. Start `easy-docker.sh` +2. Create a new stack +3. Choose `single-host` +4. Pick the apps and branches you want +5. Build the custom image +6. Start the stack +7. Create the first site or manage an existing one from the stack menu + +Use this page as the entry point. For the full workflow reference, jump to the +dedicated `easy-docker` docs section in the root `docs` tree. diff --git a/docs/10-easy-docker/01-overview.md b/docs/10-easy-docker/01-overview.md new file mode 100644 index 00000000..7f9b08cd --- /dev/null +++ b/docs/10-easy-docker/01-overview.md @@ -0,0 +1,32 @@ +--- +title: Overview +--- + +# Overview + +`easy-docker` guides the main stack lifecycle through menus instead of requiring +users to assemble long Docker and Bench commands by hand. + +Current scope: + +- create a stack +- choose the topology +- configure apps and branches +- build the custom image +- start, restart, stop, and delete the stack +- create and manage a site +- install and uninstall apps on an existing site +- create a site backup + +Current limitations: + +- `single-host` is the supported path +- `split-services` is still marked as in development +- site management currently assumes one configured site per stack +- backup and app management are focused on the configured stack image and site + +The current entrypoint is: + +```bash +bash easy-docker.sh +``` diff --git a/docs/10-easy-docker/02-workflows.md b/docs/10-easy-docker/02-workflows.md new file mode 100644 index 00000000..02f3deb3 --- /dev/null +++ b/docs/10-easy-docker/02-workflows.md @@ -0,0 +1,27 @@ +--- +title: Workflows +--- + +# Workflows + +The wizard follows a simple order: + +1. Create a stack. +2. Choose `single-host` or review `split-services`. +3. Select the apps and branches for the stack. +4. Generate the stack environment and render the Compose snapshot. +5. Build the custom image. +6. Start the stack. +7. Create or select the configured site. +8. Manage site apps or create a backup. + +Stack actions are grouped around image and Compose lifecycle: + +- `Apps` manages the stack app selection +- `Updates` handles app-branch changes and custom image tag updates +- `Site` handles site creation, backup, install, uninstall, and deletion +- `Start`, `Restart`, `Stop`, and `Delete` control the Compose lifecycle + +Site app management is intentionally scoped to apps that are already part of the +stack image. The wizard does not try to install arbitrary apps that are not part +of the selected stack configuration. diff --git a/docs/10-easy-docker/03-updates.md b/docs/10-easy-docker/03-updates.md new file mode 100644 index 00000000..2db70fef --- /dev/null +++ b/docs/10-easy-docker/03-updates.md @@ -0,0 +1,26 @@ +--- +title: Updates +--- + +# Updates + +App updates are handled as an image update workflow, not as a live in-container +`git pull`. + +The recommended sequence is: + +1. Update the selected app branches. +2. Set a new `CUSTOM_TAG`. +3. Build the updated custom image. +4. Restart the stack. +5. Run `migrate` on the site if required by the app change. + +The wizard keeps the current `frappe_branch` visible while you update apps so +you can see the base version the stack is built against. + +`CUSTOM_TAG` is stored in the stack `.env` file. The Compose stack reads that +value on the next start or restart, so the tag change becomes effective once the +image has been rebuilt and the stack is restarted. + +For now, this update flow focuses on app branch changes. A separate Frappe base +version update flow can be added later without changing the overall model. diff --git a/docs/10-easy-docker/04-generated-compose.md b/docs/10-easy-docker/04-generated-compose.md new file mode 100644 index 00000000..968a42a0 --- /dev/null +++ b/docs/10-easy-docker/04-generated-compose.md @@ -0,0 +1,23 @@ +--- +title: Generated Compose +--- + +# Generated Compose + +`easy-docker` can render a `compose.generated.yaml` snapshot from the stack +metadata and environment. + +This file is useful when you want to inspect or reuse the resolved Compose +configuration outside the wizard, but it is not the primary runtime input for +stack start or stop. + +What is important: + +- the stack runtime reads the original Compose files from metadata +- the runtime also reads the stack `.env` +- `compose.generated.yaml` is a rendered snapshot, not the source of truth +- it is refreshed after a successful custom image build + +That means the generated file stays aligned with the current stack state when the +image has actually been rebuilt, which is the point where manual reuse is most +likely to matter. diff --git a/docs/10-easy-docker/index.md b/docs/10-easy-docker/index.md new file mode 100644 index 00000000..3b005f8d --- /dev/null +++ b/docs/10-easy-docker/index.md @@ -0,0 +1,23 @@ +--- +title: Easy Docker +--- + +# Easy Docker + +`easy-docker` is the interactive setup and management workflow for this repository. +It is designed to make common Frappe Docker tasks easier from the terminal while +keeping the underlying Compose and Bench model visible. + +This section documents the current behavior of the wizard: + +- `single-host` is the supported production workflow today +- `split-services` is still in development +- stack, site, app, and update actions are handled through the wizard +- the generated Compose output is available as a rendered snapshot + +Start here: + +- [Overview](./01-overview.md) +- [Workflows](./02-workflows.md) +- [Updates](./03-updates.md) +- [Generated Compose](./04-generated-compose.md)