diff --git a/docs/10-easy-docker/01-overview.md b/docs/10-easy-docker/01-overview.md index bab00fab..b05f1a8c 100644 --- a/docs/10-easy-docker/01-overview.md +++ b/docs/10-easy-docker/01-overview.md @@ -4,32 +4,206 @@ 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. +`easy-docker` is the guided terminal workflow for setting up and managing a +Frappe Docker stack from one place. -Current scope: +Instead of collecting Docker Compose, image build, and Bench commands manually, +you move through a small set of menus that guide the main lifecycle of a stack. -- create a stack -- choose the topology -- configure apps and branches +The interface is powered by `gum`, which is used to render the interactive +terminal menus and prompts. + +All stack data created by the wizard is written into the repository-local +`.easy-docker` directory. That includes the generated stack environment files +and the stack-specific metadata used by the workflow. + +This means `easy-docker` is not a closed system. After the setup has been +created, you can still inspect the generated files, keep working with them +manually, and continue outside the wizard if that fits your workflow better. + +## What It Helps With + +`easy-docker` is built to make the usual stack workflow easier to follow: + +- create a new stack +- choose the stack setup path +- select apps and branches +- generate the stack environment - build the custom image -- start, restart, stop, and delete the stack +- start, stop, restart, or delete the stack - create and manage a site -- install and uninstall apps on an existing site -- create a site backup +- install or uninstall apps on the site +- create backups and run site maintenance actions -Current limitations: +## How It Feels to Use -- `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 workflow is organized as a guided sequence. -Current setup-type behavior: +You start with a stack, define how it should be configured, let the wizard write +the stack files, then continue into the management area for image, runtime, and +site actions. -- `development` stacks enable `developer_mode` automatically for newly created sites +This makes `easy-docker` useful both for first-time setup and for returning to +an existing stack later when you need to update apps, rebuild an image, restart +services, or work on the site itself. -The current entrypoint is: +If you have not worked with a guided Docker setup before, it helps to think of +`easy-docker` as a step-by-step assistant. It does not ask you to memorize the +Docker commands first. Instead, it asks a small number of questions, writes the +stack configuration for you, and then gives you a menu for the most common next +actions. + +![Easy Docker main menu](../images/easy-docker/overview/main-menu.png) + +## What It Needs + +To run `easy-docker`, the environment should have: + +- a working `docker` CLI +- Docker Compose v2 through `docker compose` +- a running Docker daemon +- `gum` for the interactive terminal UI + +When `gum` is already installed, the wizard uses it directly. + +When `gum` is missing, `easy-docker` first tries to install it through the +system package manager. If that is not available or does not succeed, the +wizard can fall back to a pinned GitHub release and install `gum` +automatically when possible. + +This means the usual setup flow is: + +- check whether `gum` is already available +- try package-manager installation first +- use the verified fallback path only if needed +- continue into the wizard once the required tooling is ready + +The Docker requirements are also checked on startup so the workflow stops early +with guidance instead of failing later in the middle of stack setup. + +## Main Areas + +### Stack Creation + +The stack creation flow collects the main decisions up front and stores them in +the stack directory so the workflow can be resumed later. + +This is where you define the stack identity, choose the setup path, and prepare +the generated configuration for the next steps. + +A typical stack creation run moves through these prompts: + +1. Name the stack and choose the Frappe version profile. + +The stack name is simply the label under which `easy-docker` will remember this +setup. If you plan to run more than one setup later, choose a name that makes +the purpose obvious. + +The Frappe version profile is the base version the stack should start from. If +you are unsure, pick the version you intend to use for the actual project or +the version your apps are built for. + +![Stack name](../images/easy-docker/overview/stack-creation/name.png) + +![Frappe version profile](../images/easy-docker/overview/stack-creation/frappe-version.png) + +2. Choose the deployment topology and the main infrastructure options. + +In this phase, the wizard asks how the stack should be structured. For most +users, this is the point where you choose the simplest practical setup and let +the wizard generate the rest of the configuration around it. + +The proxy and database choices decide how traffic reaches the stack and where +the site data is stored. Even if you do not know every Docker detail yet, the +important part is that these choices describe how your stack should behave once +it is running. + +![Topology selection](../images/easy-docker/overview/stack-creation/topology.png) + +![Proxy mode selection](../images/easy-docker/overview/stack-creation/proxy-mode.png) + +![Database selection](../images/easy-docker/overview/stack-creation/database.png) + +3. Define the image naming and versioning that should be used for the stack. + +This step controls the image that will later be built for your stack. You can +think of it as naming the packaged application that Docker should run. + +The image name identifies the image, while the image version or tag helps you +track which build you are currently using. That becomes especially useful when +you rebuild the stack after changing app branches or updating the setup. + +![Custom image naming](../images/easy-docker/overview/stack-creation/image-name.png) + +![Custom image version](../images/easy-docker/overview/stack-creation/image-version.png) + +4. Select the apps and branches that should be built into the stack image. + +This is the point where you decide what should actually be included in the +stack. The app selection defines the application set, and the branch selection +defines which code line of each app should be used for the build. + +For new users, the practical rule is simple: only include the apps you really +need, and choose branches that match the Frappe version profile you selected +earlier. + +![App selection](../images/easy-docker/overview/stack-creation/app-selection.png) + +![App version selection](../images/easy-docker/overview/stack-creation/app-version.png) + +After these decisions, `easy-docker` has enough information to write the stack +files and prepare the next phase. At that point, the workflow moves from +planning the stack to actually building and running it. + +### Stack Management + +Once a stack exists, `easy-docker` becomes the control point for the stack: + +- app selection and branch updates +- custom image build and rebuild +- Compose lifecycle actions +- site operations such as create, migrate, backup, and delete + +That means the same workflow continues after setup instead of ending once the +first stack files are written. + +The first management steps usually focus on preparing the image and bringing the +stack up in Docker Compose. + +The build step creates the actual Docker image for the stack you just defined. +Until that image exists, there is nothing concrete for Docker Compose to start. +That is why the build action comes before the start action. + +![Build image action](../images/easy-docker/overview/stack-management/build-image.png) + +Once the image has been built successfully, you can start the stack. This tells +Docker Compose to create the containers and launch the services that belong to +your setup. + +![Start stack action](../images/easy-docker/overview/stack-management/start-stack.png) + +After startup, the status view helps you confirm that the stack is actually +running. This is especially useful for beginners because it gives a visible +checkpoint before moving on to site creation or later maintenance steps. + +![Running stack status](../images/easy-docker/overview/stack-management/running-stack.png) + +From there, the workflow usually continues into site-level actions such as +creating the first site, installing apps on the site, running migrations, or +creating backups. In other words: stack creation defines the environment, and +stack management is where that environment becomes usable. + +### Development Stacks + +When you create a stack through the development path, newly created sites in +that stack automatically enable `developer_mode`. + +This keeps the development-specific behavior attached to the stack itself, so +the workflow stays consistent when you return to manage it later. + +## Entry Point + +Run the wizard from the repository root: ```bash bash easy-docker.sh diff --git a/docs/images/easy-docker/overview/main-menu.png b/docs/images/easy-docker/overview/main-menu.png new file mode 100644 index 00000000..5f1b078f Binary files /dev/null and b/docs/images/easy-docker/overview/main-menu.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/app-selection.png b/docs/images/easy-docker/overview/stack-creation/app-selection.png new file mode 100644 index 00000000..bd30bc0f Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/app-selection.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/app-version.png b/docs/images/easy-docker/overview/stack-creation/app-version.png new file mode 100644 index 00000000..4b16d755 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/app-version.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/database.png b/docs/images/easy-docker/overview/stack-creation/database.png new file mode 100644 index 00000000..f6f26a19 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/database.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/frappe-version.png b/docs/images/easy-docker/overview/stack-creation/frappe-version.png new file mode 100644 index 00000000..6ac62933 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/frappe-version.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/image-name.png b/docs/images/easy-docker/overview/stack-creation/image-name.png new file mode 100644 index 00000000..499a603a Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/image-name.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/image-version.png b/docs/images/easy-docker/overview/stack-creation/image-version.png new file mode 100644 index 00000000..b4333e3b Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/image-version.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/name.png b/docs/images/easy-docker/overview/stack-creation/name.png new file mode 100644 index 00000000..2a07299b Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/name.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/proxy-mode.png b/docs/images/easy-docker/overview/stack-creation/proxy-mode.png new file mode 100644 index 00000000..4417b31b Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/proxy-mode.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/topology.png b/docs/images/easy-docker/overview/stack-creation/topology.png new file mode 100644 index 00000000..da815928 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-creation/topology.png differ diff --git a/docs/images/easy-docker/overview/stack-management/build-image.png b/docs/images/easy-docker/overview/stack-management/build-image.png new file mode 100644 index 00000000..51a1ac3e Binary files /dev/null and b/docs/images/easy-docker/overview/stack-management/build-image.png differ diff --git a/docs/images/easy-docker/overview/stack-management/running-stack.png b/docs/images/easy-docker/overview/stack-management/running-stack.png new file mode 100644 index 00000000..30f239f7 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-management/running-stack.png differ diff --git a/docs/images/easy-docker/overview/stack-management/start-stack.png b/docs/images/easy-docker/overview/stack-management/start-stack.png new file mode 100644 index 00000000..61fcf574 Binary files /dev/null and b/docs/images/easy-docker/overview/stack-management/start-stack.png differ