diff --git a/docs/01-getting-started/05-easy-docker.md b/docs/01-getting-started/05-easy-docker.md index 55d1038c..e3d5041b 100644 --- a/docs/01-getting-started/05-easy-docker.md +++ b/docs/01-getting-started/05-easy-docker.md @@ -14,7 +14,8 @@ 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 +- `split-services` is available for separated stack setup and Compose runtime control +- site actions currently remain part of the `single-host` workflow - stack, site, app, backup, restart, and update flows are being expanded iteratively The script entrypoint is: diff --git a/docs/10-easy-docker/01-overview.md b/docs/10-easy-docker/01-overview.md index b05f1a8c..b1ee3bbf 100644 --- a/docs/10-easy-docker/01-overview.md +++ b/docs/10-easy-docker/01-overview.md @@ -53,7 +53,7 @@ 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) +![Easy Docker main menu](../images/easy-docker/entry/main-menu.png) ## What It Needs @@ -103,9 +103,9 @@ 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) +![Stack name](../images/easy-docker/stack-creation/core/name.png) -![Frappe version profile](../images/easy-docker/overview/stack-creation/frappe-version.png) +![Frappe version profile](../images/easy-docker/stack-creation/core/frappe-version.png) 2. Choose the deployment topology and the main infrastructure options. @@ -118,11 +118,11 @@ 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) +![Topology selection](../images/easy-docker/stack-creation/topology/topology-menu.png) -![Proxy mode selection](../images/easy-docker/overview/stack-creation/proxy-mode.png) +![Proxy mode selection](../images/easy-docker/single-host/proxy-mode.png) -![Database selection](../images/easy-docker/overview/stack-creation/database.png) +![Database selection](../images/easy-docker/single-host/database-engine.png) 3. Define the image naming and versioning that should be used for the stack. @@ -133,9 +133,9 @@ 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 naming](../images/easy-docker/stack-creation/image/image-name.png) -![Custom image version](../images/easy-docker/overview/stack-creation/image-version.png) +![Custom image version](../images/easy-docker/stack-creation/image/image-version.png) 4. Select the apps and branches that should be built into the stack image. @@ -147,9 +147,9 @@ 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 selection](../images/easy-docker/stack-creation/apps/app-selection.png) -![App version selection](../images/easy-docker/overview/stack-creation/app-version.png) +![App version selection](../images/easy-docker/stack-creation/apps/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 @@ -174,19 +174,23 @@ 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) +![Build image action](../images/easy-docker/stack-runtime/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) +![Start stack action](../images/easy-docker/stack-runtime/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) +![Running stack status](../images/easy-docker/stack-runtime/running-stack.png) + +In this example, the one stopped container shown in the status output is the +`configurator` container. That container is expected to finish and stop after +its setup work has completed. From there, the workflow usually continues into site-level actions such as creating the first site, installing apps on the site, running migrations, or diff --git a/docs/10-easy-docker/02-workflows.md b/docs/10-easy-docker/02-workflows.md index 02f3deb3..7b5b72ae 100644 --- a/docs/10-easy-docker/02-workflows.md +++ b/docs/10-easy-docker/02-workflows.md @@ -7,13 +7,12 @@ title: Workflows The wizard follows a simple order: 1. Create a stack. -2. Choose `single-host` or review `split-services`. +2. Choose `single-host` or `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. +7. Continue into site actions when the selected workflow supports them. Stack actions are grouped around image and Compose lifecycle: @@ -25,3 +24,8 @@ Stack actions are grouped around image and 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. + +For the split-services path, see +[Split Services](./05-split-services.md). That page explains the intended flow +in simple terms and shows where the proxy, application, database, and Redis +choices fit into the setup. diff --git a/docs/10-easy-docker/05-split-services.md b/docs/10-easy-docker/05-split-services.md new file mode 100644 index 00000000..5e02e3d1 --- /dev/null +++ b/docs/10-easy-docker/05-split-services.md @@ -0,0 +1,215 @@ +--- +title: Split Services +--- + +# Split Services + +`split-services` is the guided setup path for users who want to keep the +application part of the stack separate from the data part, with an optional +proxy layer in front. + +The goal of this page is to help a first-time user understand what each step +means and what choice they are making in the wizard. + +The current split-services flow focuses on: + +- writing the split stack files +- rendering the generated Compose snapshot +- building the custom image +- starting, stopping, restarting, and deleting the stack + +This keeps the first version easier to understand while still making the stack +layout explicit. + +Think of the split-services setup as three simple parts: + +- `Application Services` run the Frappe application itself +- `Data Services` provide the database and Redis services +- `Reverse Proxy` handles incoming web traffic when you want a proxy in front + +This page uses the clearer names above so the setup is easier to understand the +first time you see it. + +## What This Setup Is For + +Split services are useful when you do not want every service in one combined +stack. + +This is a good fit if you want to: + +- keep the application layer separate from the data layer +- run the database and Redis independently from the app stack +- place a proxy in front only when you actually need it +- keep the setup readable so you can manage parts of it later + +If you are new to Docker, you can think of this as splitting one big stack into +smaller parts that each have a clearer job. + +## How The Wizard Feels + +The wizard still behaves like the other `easy-docker` flows. + +It asks one question at a time, explains what that choice affects, and then +writes the stack files for you. You do not need to build the final Compose +files by hand before you start. + +![Split Services topology menu](../images/easy-docker/split-services/topology-menu.png) + +## Step 1. Choose The Split Topology + +When you select `Split services`, the wizard first explains that the stack is +being divided into separate parts instead of using one combined setup. + +At this point you are not changing any service settings yet. You are only +choosing the layout of the stack. + +This matters because later steps will follow the same idea. If the setup is +split, the wizard will ask about the application side, the data side, and the +proxy side separately. + +## Step 2. Decide How The Data Services Should Work + +The next decision is the data layer. + +This is where you decide whether `easy-docker` manages the database and Redis +for you, or whether the stack should connect to services that already exist +elsewhere. + +### Managed Data Services + +Choose this if you want `easy-docker` to create the database and Redis +containers as part of the generated split setup. + +This is usually the easier choice when you are trying split-services for the +first time. + +It means: + +- the wizard writes the data service configuration for you +- the stack can start with its own managed database and Redis services +- you still keep the data layer separate from the application layer + +### External Data Services + +Choose this if the database and Redis are already running somewhere else. + +This is more advanced, but it can be useful when: + +- your organization already provides shared database and Redis services +- you want the application stack to connect to existing infrastructure +- you are splitting responsibilities across different systems + +If you choose this path, the wizard asks for the required connection values and +stores them in the generated stack configuration. + +![Data services choice](../images/easy-docker/split-services/data-services-choice.png) + +## Step 3. Choose The Database Engine + +After choosing how the data layer should be handled, the wizard asks which +database engine should be used for the stack. + +For most users, this is the simpler way to think about it: + +- `MariaDB` is the default path and usually the easiest starting point +- `PostgreSQL` is available if that is the database you already use or want to use + +If the data layer is managed by `easy-docker`, this choice decides which +database service will be created in the generated setup. + +If the data layer is external, this choice still matters because it tells the +stack which kind of database it is configured to connect to. + +![Database engine choice](../images/easy-docker/split-services/database-engine.png) + +## Step 4. Decide How Redis Should Work + +Redis is asked about separately so the setup stays explicit. + +This is useful because some users want Redis managed together with the split +stack, while others already have Redis running elsewhere. + +The choices are simple: + +- `Managed Redis Services` means the stack includes Redis services for you +- `External Redis Services` means you provide the Redis endpoints yourself +- `No Redis Services` is the advanced option when you do not want the wizard to + configure Redis for this stack + +The important beginner-friendly idea is that Redis belongs to the data side of +the setup, even though it is asked in its own step. + +![Redis services choice](../images/easy-docker/split-services/redis-services.png) + +## Step 5. Decide Whether A Proxy Should Be Included + +The proxy layer is optional. + +If you want the stack to answer HTTP or HTTPS traffic directly in front of the +application services, include a proxy. + +If you do not need that yet, you can skip it and keep the setup simpler. + +For a first-time user, the important idea is: + +- the proxy is the front door +- the application services do the actual work +- the data services keep the site data and queue state safe + +![Proxy choice](../images/easy-docker/split-services/proxy-choice.png) + +## Step 6. Review The Setup Before It Is Written + +Before the wizard writes the files, it shows a summary of the choices you just +made. + +This summary is the last chance to stop and check whether the stack is shaped +the way you expected. + +The summary makes the split very obvious: + +- what runs as application services +- what runs as data services +- whether a proxy is included +- whether the data services are managed by `easy-docker` or external + +![Split services summary](../images/easy-docker/split-services/summary.png) + +## What Happens After Setup + +Once the split stack has been written, the generated files are stored in the +same repository-local `.easy-docker` area as the other wizard data. + +That means you can still inspect the generated files later and continue working +with them manually if needed. + +After the files are written, the wizard returns to the stack management view for +that split-services stack. From there you can work with the stack runtime, app +selection, and update actions that are currently supported for this topology. + +![Split Services manage stack actions](../images/easy-docker/split-services/manage-stack-actions.png) + +For split-services, the most important practical point is that the application +side, the data side, and the proxy side remain easy to understand +individually. If you come back later to change one part, you should not have to +guess where the other parts are defined. + +## A Simple Mental Model + +If this is the first time you use a split setup, this is the easiest way to +think about it: + +- `Application Services` are the part you interact with most often +- `Data Services` keep the database and Redis available +- `Reverse Proxy` is optional and sits in front of the application side + +You do not need to understand every Docker detail before using the wizard. +You only need to know which part you want to manage separately. + +## Where To Go Next + +After reading this page, the next useful pages are: + +- [Overview](./01-overview.md) +- [Workflows](./02-workflows.md) +- [Generated Compose](./04-generated-compose.md) diff --git a/docs/10-easy-docker/index.md b/docs/10-easy-docker/index.md index 3b005f8d..ff79c647 100644 --- a/docs/10-easy-docker/index.md +++ b/docs/10-easy-docker/index.md @@ -11,7 +11,8 @@ 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 +- `split-services` is available for separated stack setup and Compose runtime control +- site actions currently remain part of the `single-host` workflow - stack, site, app, and update actions are handled through the wizard - the generated Compose output is available as a rendered snapshot @@ -21,3 +22,4 @@ Start here: - [Workflows](./02-workflows.md) - [Updates](./03-updates.md) - [Generated Compose](./04-generated-compose.md) +- [Split Services](./05-split-services.md) diff --git a/docs/images/easy-docker/overview/main-menu.png b/docs/images/easy-docker/entry/main-menu.png similarity index 100% rename from docs/images/easy-docker/overview/main-menu.png rename to docs/images/easy-docker/entry/main-menu.png diff --git a/docs/images/easy-docker/overview/stack-creation/topology.png b/docs/images/easy-docker/overview/stack-creation/topology.png deleted file mode 100644 index da815928..00000000 Binary files a/docs/images/easy-docker/overview/stack-creation/topology.png and /dev/null differ diff --git a/docs/images/easy-docker/overview/stack-creation/database.png b/docs/images/easy-docker/single-host/database-engine.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/database.png rename to docs/images/easy-docker/single-host/database-engine.png diff --git a/docs/images/easy-docker/overview/stack-creation/proxy-mode.png b/docs/images/easy-docker/single-host/proxy-mode.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/proxy-mode.png rename to docs/images/easy-docker/single-host/proxy-mode.png diff --git a/docs/images/easy-docker/split-services/data-services-choice.png b/docs/images/easy-docker/split-services/data-services-choice.png new file mode 100644 index 00000000..7a356daf Binary files /dev/null and b/docs/images/easy-docker/split-services/data-services-choice.png differ diff --git a/docs/images/easy-docker/split-services/database-engine.png b/docs/images/easy-docker/split-services/database-engine.png new file mode 100644 index 00000000..1d30fe6c Binary files /dev/null and b/docs/images/easy-docker/split-services/database-engine.png differ diff --git a/docs/images/easy-docker/split-services/manage-stack-actions.png b/docs/images/easy-docker/split-services/manage-stack-actions.png new file mode 100644 index 00000000..1d811526 Binary files /dev/null and b/docs/images/easy-docker/split-services/manage-stack-actions.png differ diff --git a/docs/images/easy-docker/split-services/proxy-choice.png b/docs/images/easy-docker/split-services/proxy-choice.png new file mode 100644 index 00000000..6c8a79eb Binary files /dev/null and b/docs/images/easy-docker/split-services/proxy-choice.png differ diff --git a/docs/images/easy-docker/split-services/redis-services.png b/docs/images/easy-docker/split-services/redis-services.png new file mode 100644 index 00000000..1de6e294 Binary files /dev/null and b/docs/images/easy-docker/split-services/redis-services.png differ diff --git a/docs/images/easy-docker/split-services/summary.png b/docs/images/easy-docker/split-services/summary.png new file mode 100644 index 00000000..9b5da88c Binary files /dev/null and b/docs/images/easy-docker/split-services/summary.png differ diff --git a/docs/images/easy-docker/split-services/topology-menu.png b/docs/images/easy-docker/split-services/topology-menu.png new file mode 100644 index 00000000..ffe8b8f1 Binary files /dev/null and b/docs/images/easy-docker/split-services/topology-menu.png differ diff --git a/docs/images/easy-docker/overview/stack-creation/app-selection.png b/docs/images/easy-docker/stack-creation/apps/app-selection.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/app-selection.png rename to docs/images/easy-docker/stack-creation/apps/app-selection.png diff --git a/docs/images/easy-docker/overview/stack-creation/app-version.png b/docs/images/easy-docker/stack-creation/apps/app-version.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/app-version.png rename to docs/images/easy-docker/stack-creation/apps/app-version.png diff --git a/docs/images/easy-docker/overview/stack-creation/frappe-version.png b/docs/images/easy-docker/stack-creation/core/frappe-version.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/frappe-version.png rename to docs/images/easy-docker/stack-creation/core/frappe-version.png diff --git a/docs/images/easy-docker/overview/stack-creation/name.png b/docs/images/easy-docker/stack-creation/core/name.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/name.png rename to docs/images/easy-docker/stack-creation/core/name.png diff --git a/docs/images/easy-docker/overview/stack-creation/image-name.png b/docs/images/easy-docker/stack-creation/image/image-name.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/image-name.png rename to docs/images/easy-docker/stack-creation/image/image-name.png diff --git a/docs/images/easy-docker/overview/stack-creation/image-version.png b/docs/images/easy-docker/stack-creation/image/image-version.png similarity index 100% rename from docs/images/easy-docker/overview/stack-creation/image-version.png rename to docs/images/easy-docker/stack-creation/image/image-version.png diff --git a/docs/images/easy-docker/stack-creation/topology/topology-menu.png b/docs/images/easy-docker/stack-creation/topology/topology-menu.png new file mode 100644 index 00000000..6953e8f2 Binary files /dev/null and b/docs/images/easy-docker/stack-creation/topology/topology-menu.png differ diff --git a/docs/images/easy-docker/overview/stack-management/build-image.png b/docs/images/easy-docker/stack-runtime/build-image.png similarity index 100% rename from docs/images/easy-docker/overview/stack-management/build-image.png rename to docs/images/easy-docker/stack-runtime/build-image.png diff --git a/docs/images/easy-docker/overview/stack-management/running-stack.png b/docs/images/easy-docker/stack-runtime/running-stack.png similarity index 100% rename from docs/images/easy-docker/overview/stack-management/running-stack.png rename to docs/images/easy-docker/stack-runtime/running-stack.png diff --git a/docs/images/easy-docker/overview/stack-management/start-stack.png b/docs/images/easy-docker/stack-runtime/start-stack.png similarity index 100% rename from docs/images/easy-docker/overview/stack-management/start-stack.png rename to docs/images/easy-docker/stack-runtime/start-stack.png