docs: move container-setup to 02-setup and integrate setup-options content

Move container-setup directory from 08-reference/ to 02-setup/ to follow
PR feedback. The container-setup documentation provides a more linear
and coherent flow compared to the previous unstructured setup files.

Changes:
- Move container-setup/ from docs/08-reference/ to docs/02-setup/
- Integrate content from setup-options.md into structured flow:
  - Create new 06-setup-examples.md with practical deployment scenarios
  - Enhance 03-start-setup.md with site creation details from setup-options
  - Remove redundant 01-setup-options.md (content now integrated)
- Rename 02-single-server-example.md to 07-single-server-example.md
- Update all cross-references throughout documentation:
  - Update README.md with new structure under Setup section
  - Fix links in site-operations.md and migration docs
  - Add navigation links between container-setup files and examples
- Maintain container-setup's linear flow: overview → build → start → env → overrides
- Add practical examples document (06-setup-examples.md) that follows the container-setup guide

Result: Documentation now follows a clear progression from conceptual
overview through practical examples, with all setup information properly
organized under 02-setup/.

README.md

@@ -62,8 +62,13 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose
 
 ### [Setup](#setup)
 
-- [Setup Options](docs/02-setup/01-setup-options.md)
-- [Single Server Example](docs/02-setup/02-single-server-example.md)
+- [Container Setup Overview](docs/02-setup/container-setup/01-overview.md)
+- [Build Setup](docs/02-setup/container-setup/02-build-setup.md)
+- [Start Setup](docs/02-setup/container-setup/03-start-setup.md)
+- [Environment Variables](docs/02-setup/container-setup/04-env-variables.md)
+- [Compose Overrides](docs/02-setup/container-setup/05-overrides.md)
+- [Setup Examples](docs/02-setup/06-setup-examples.md)
+- [Single Server Example](docs/02-setup/07-single-server-example.md)
 
 ### [Production](#production)
 
@@ -92,11 +97,6 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose
 
 ### [Reference](#reference)
 
-- [Container Setup Overview](docs/08-reference/container-setup/01-overview.md)
-- [Build Setup](docs/08-reference/container-setup/02-build-setup.md)
-- [Start Setup](docs/08-reference/container-setup/03-start-setup.md)
-- [Environment Variables](docs/08-reference/container-setup/04-env-variables.md)
-- [Compose Overrides](docs/08-reference/container-setup/05-overrides.md)
 - [Build Version 10 Images](docs/08-reference/01-build-version-10-images.md)
 
 # Contributing

docs/02-setup/01-setup-options.md

@@ -1,131 +0,0 @@
-# Containerized Production Setup
-
-Make sure you've cloned this repository and switch to the directory before executing following commands.
-
-Commands will generate YAML as per the environment for setup.
-
-## Prerequisites
-
-- [docker](https://docker.com/get-started)
-- [docker compose v2](https://docs.docker.com/compose/cli-command)
-
-## Setup Environment Variables
-
-Copy the example docker environment file to `.env`:
-
-```sh
-cp example.env .env
-```
-
-Note: To know more about environment variable [read here](../08-reference/container-setup/04-env-variables.md). Set the necessary variables in the `.env` file.
-
-## Generate docker-compose.yml for variety of setups
-
-Notes:
-
-- Make sure to replace `<project-name>` with the desired name you wish to set for the project.
-- This setup is not to be used for development. A complete development environment is available [here](../development)
-
-### Store the yaml files
-
-YAML files generated by `docker compose config` command can be stored in a directory. We will create a directory called `gitops` in the user's home.
-
-```shell
-mkdir ~/gitops
-```
-
-You can make the directory into a private git repo which stores the yaml and secrets. It can help in tracking changes.
-
-Instead of `docker compose config`, you can directly use `docker compose up` to start the containers and skip storing the yamls in `gitops` directory.
-
-### Setup Frappe without proxy and external MariaDB and Redis
-
-In this case make sure you've set `DB_HOST`, `DB_PORT`, `REDIS_CACHE` and `REDIS_QUEUE` environment variables or the `configurator` will fail.
-
-```sh
-# Generate YAML
-docker compose -f compose.yaml -f overrides/compose.noproxy.yaml config > ~/gitops/docker-compose.yml
-
-# Start containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
-```
-
-### Setup ERPNext with proxy and external MariaDB and Redis
-
-In this case make sure you've set `DB_HOST`, `DB_PORT`, `REDIS_CACHE` and `REDIS_QUEUE` environment variables or the `configurator` will fail.
-
-```sh
-# Generate YAML
-docker compose -f compose.yaml \
-  -f overrides/compose.proxy.yaml \
-  config > ~/gitops/docker-compose.yml
-
-# Start containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
-```
-
-### Setup Frappe using containerized MariaDB and Redis with Letsencrypt certificates.
-
-In this case make sure you've set `LETSENCRYPT_EMAIL` and `SITES` environment variables are set or certificates won't work.
-
-```sh
-# Generate YAML
-docker compose -f compose.yaml \
-  -f overrides/compose.mariadb.yaml \
-  -f overrides/compose.redis.yaml \
-  -f overrides/compose.https.yaml \
-  config > ~/gitops/docker-compose.yml
-
-# Start containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
-```
-
-### Setup ERPNext using containerized MariaDB and Redis with Letsencrypt certificates.
-
-In this case make sure you've set `LETSENCRYPT_EMAIL` and `SITES` environment variables are set or certificates won't work.
-
-```sh
-# Generate YAML
-docker compose -f compose.yaml \
-  -f overrides/compose.mariadb.yaml \
-  -f overrides/compose.redis.yaml \
-  -f overrides/compose.https.yaml \
-  config > ~/gitops/docker-compose.yml
-
-# Start containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
-```
-
-## Create first site
-
-After starting containers, the first site needs to be created. Refer [site operations](../04-operations/01-site-operations.md#setup-new-site).
-
-## Updating Images
-
-Switch to the root of the `frappe_docker` directory before running the following commands:
-
-```sh
-# Update environment variables ERPNEXT_VERSION and FRAPPE_VERSION
-nano .env
-
-# Pull new images
-docker compose -f compose.yaml \
-  # ... your other overrides
-  config > ~/gitops/docker-compose.yml
-
-# Pull images
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml pull
-
-# Stop containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml down
-
-# Restart containers
-docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
-```
-
-Note:
-
-- pull and stop container commands can be skipped if immutable image tags are used
-- `docker compose up -d` will pull new immutable tags if not found.
-
-To migrate sites refer [site operations](../04-operations/01-site-operations.md#migrate-site)

docs/02-setup/06-setup-examples.md

@@ -0,0 +1,135 @@
+# Setup Examples
+
+This guide provides practical examples for common setup scenarios. These examples build upon the [container setup guide](container-setup/01-overview.md) and demonstrate how to combine the base compose file with overrides.
+
+> **Note:** This setup is not for development. A complete development environment is available [here](../05-development/01-development.md).
+
+## Prerequisites
+
+- [docker](https://docker.com/get-started)
+- [docker compose v2](https://docs.docker.com/compose/cli-command)
+- Cloned `frappe_docker` repository
+
+## Setup Environment Variables
+
+Copy the example docker environment file to `.env`:
+
+```sh
+cp example.env .env
+```
+
+Edit `.env` and set variables according to your needs. See [environment variables](container-setup/04-env-variables.md) for detailed descriptions of all available variables.
+
+## Storing Generated YAML Files
+
+YAML files generated by `docker compose config` can be stored in a directory for version control and management:
+
+```shell
+mkdir ~/gitops
+```
+
+You can make this directory into a private git repository to track changes to your configuration. This is especially useful for managing multiple environments or projects.
+
+Alternatively, you can directly use `docker compose up` to start containers without storing intermediate YAML files.
+
+## Example 1: Frappe without Proxy (Direct Access)
+
+Setup Frappe with containerized MariaDB and Redis, exposing the application directly on port `:8080` without a reverse proxy.
+
+**Requirements:**
+- Set `DB_PASSWORD` in `.env` (or use default `123`)
+- No external database or Redis needed
+
+```sh
+# Generate YAML
+docker compose -f compose.yaml \
+  -f overrides/compose.mariadb.yaml \
+  -f overrides/compose.redis.yaml \
+  -f overrides/compose.noproxy.yaml \
+  config > ~/gitops/docker-compose.yml
+
+# Start containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+```
+
+## Example 2: ERPNext with External Database and Redis
+
+Setup ERPNext using external MariaDB and Redis instances with Traefik HTTP proxy.
+
+**Requirements:**
+- Set `DB_HOST`, `DB_PORT`, `REDIS_CACHE`, and `REDIS_QUEUE` in `.env`
+- External database and Redis must be accessible
+
+```sh
+# Generate YAML
+docker compose -f compose.yaml \
+  -f overrides/compose.proxy.yaml \
+  config > ~/gitops/docker-compose.yml
+
+# Start containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+```
+
+## Example 3: Production Setup with HTTPS
+
+Setup Frappe/ERPNext using containerized MariaDB and Redis with Let's Encrypt SSL certificates via Traefik.
+
+**Requirements:**
+- Set `LETSENCRYPT_EMAIL` and `SITES` environment variables
+- DNS must point to your server IP
+
+```sh
+# Generate YAML
+docker compose -f compose.yaml \
+  -f overrides/compose.mariadb.yaml \
+  -f overrides/compose.redis.yaml \
+  -f overrides/compose.https.yaml \
+  config > ~/gitops/docker-compose.yml
+
+# Start containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+```
+
+> **Note:** Ensure your `SITES` variable is properly formatted. See [environment variables](container-setup/04-env-variables.md) for the correct format.
+
+## Create First Site
+
+After starting containers, create your first site. Refer to [site operations](../04-operations/01-site-operations.md#setup-new-site) for detailed instructions.
+
+## Updating Images
+
+To update to newer versions of Frappe or ERPNext:
+
+```sh
+# 1. Update environment variables in .env
+nano .env
+# Edit ERPNEXT_VERSION and FRAPPE_VERSION as needed
+
+# 2. Regenerate compose file with new versions
+docker compose --env-file .env \
+  -f compose.yaml \
+  # ... your other overrides
+  config > ~/gitops/docker-compose.yml
+
+# 3. Pull new images
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml pull
+
+# 4. Stop containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml down
+
+# 5. Restart containers
+docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
+```
+
+> **Note:** 
+> - Pull and stop container commands can be skipped if immutable image tags are used
+> - `docker compose up -d` will pull new immutable tags if not found
+
+To migrate sites after updating, refer to [site operations](../04-operations/01-site-operations.md#migrate-site).
+
+---
+
+**Back:** [Start Setup →](container-setup/03-start-setup.md)
+
+**Next:** [Single Server Example →](07-single-server-example.md)
+

docs/02-setup/07-single-server-example.md

@@ -1,4 +1,6 @@
-### Single Server Example
+# Single Server Example
+
+This guide demonstrates setting up multiple Frappe/ERPNext benches (projects) on a single server with shared infrastructure components.
 
 In this use case we have a single server with a static IP attached to it. It can be used in scenarios where one powerful VM has multiple benches and applications or one entry level VM with single site. For single bench, single site setup follow only up to the point where first bench and first site is added. If you choose this setup you can only scale vertically. If you need to scale horizontally you'll need to backup the sites and restore them on to cluster setup.
 
@@ -286,3 +288,7 @@ docker compose --project-name custom-one-example -f ~/gitops/custom-one-example.
 ### Site operations
 
 Refer: [site operations](../04-operations/01-site-operations.md)
+
+---
+
+**Back:** [Setup Examples →](06-setup-examples.md)

docs/02-setup/container-setup/01-overview.md

@@ -45,3 +45,5 @@ Example: The main compose file has no database service, but `compose.mariadb.yam
 ---
 
 **Next:** [Build Setup →](02-build-setup.md)
+
+**See also:** [Setup Examples](../06-setup-examples.md) for practical deployment scenarios.

docs/02-setup/container-setup/02-build-setup.md

@@ -119,3 +119,5 @@ This generates `compose.custom.yaml`, which you'll use to start all containers.
 **Next:** [Start Setup →](03-start-setup.md)
 
 **Back:** [Container Overview ←](01-overview.md)
+
+**See also:** [Setup Examples](../06-setup-examples.md) for practical deployment scenarios.

docs/02-setup/container-setup/03-start-setup.md

@@ -16,6 +16,8 @@ The `-p` (or `--project-name`) flag names the project `frappe`, allowing you to
 
 Frappe is now running, but it's not yet configured. You need to create a site and install your apps.
 
+## Basic site creation
+
 ```bash
 docker compose -p frappe exec backend bench new-site <sitename> --mariadb-user-host-login-scope='172.%.%.%'
 docker compose -p frappe exec backend bench --site <sitename> install-app erpnext
@@ -29,6 +31,22 @@ bench --site <sitename> install-app erpnext
 
 Replace `<sitename>` with your desired site name.
 
+## Create site with app installation
+
+You can install apps during site creation:
+
+```bash
+docker compose -p frappe exec backend bench new-site <sitename> \
+  --mariadb-user-host-login-scope='%' \
+  --db-root-password <db-password> \
+  --admin-password <admin-password> \
+  --install-app erpnext
+```
+
+> **Note:** Wait for the `db` service to start and `configurator` to exit before trying to create a new site. Usually this takes up to 10 seconds.
+
+For more site operations, refer to [site operations](../../04-operations/01-site-operations.md).
+
 > ## Understanding the MariaDB User Scope
 >
 > The flag --mariadb-user-host-login-scope='172.%.%.%' allows database connections from any IP address within the 172.0.0.0/8 range. This includes all containers and virtual machines running on your machine.
@@ -40,3 +58,5 @@ Replace `<sitename>` with your desired site name.
 ---
 
 **Back:** [Build Setup →](02-build-setup.md)
+
+**Next:** [Setup Examples →](../06-setup-examples.md)

docs/04-operations/01-site-operations.md

@@ -15,7 +15,7 @@ docker-compose exec backend bench new-site --mariadb-user-host-login-scope=% --d
 
 If you need to install some app, specify `--install-app`. To see all options, just run `bench new-site --help`.
 
-To create Postgres site (assuming you already use [Postgres compose override](../08-reference/container-setup/05-overrides.md)) you need have to do set `root_login` and `root_password` in common config before that:
+To create Postgres site (assuming you already use [Postgres compose override](../02-setup/container-setup/05-overrides.md)) you need have to do set `root_login` and `root_password` in common config before that:
 
 ```sh
 docker-compose exec backend bench set-config -g root_login <root-login>

docs/06-migration/01-migrate-from-multi-image-setup.md

@@ -6,7 +6,7 @@ Now you need to specify command and environment variables for following containe
 
 ### Frontend
 
-For `frontend` service to act as static assets frontend and reverse proxy, you need to pass `nginx-entrypoint.sh` as container `command` and `BACKEND` and `SOCKETIO` environment variables pointing `{host}:{port}` for gunicorn and websocket services. Check [environment variables](../08-reference/container-setup/04-env-variables.md)
+For `frontend` service to act as static assets frontend and reverse proxy, you need to pass `nginx-entrypoint.sh` as container `command` and `BACKEND` and `SOCKETIO` environment variables pointing `{host}:{port}` for gunicorn and websocket services. Check [environment variables](../02-setup/container-setup/04-env-variables.md)
 
 Now you only need to mount the `sites` volume at location `/home/frappe/frappe-bench/sites`. No need for `assets` volume and asset population script or steps.