docs: reorganize documentation structure with numbered navigation (#1729)

* docs: reorganize documentation structure into logical categories

Restructure documentation into organized directories for better navigation:

- getting-started/: Quick start guides for new users
- setup/: Setup and configuration guides
- production/: Production deployment guides (backup, TLS, multi-tenancy)
- operations/: Site operations and management
- development/: Development workflow guides
- migration/: Migration guides
- troubleshooting/: Troubleshooting guides
- reference/: Reference documentation (container setup, build configs)

Rename files for consistency:
- Use kebab-case naming convention throughout
- Remove numbered prefixes from container-setup files
- Use descriptive names (backup-strategy, tls-ssl-setup, etc.)

Update all internal cross-references to reflect new file locations.
Update README.md with organized documentation structure.
Fix image paths in development.md to use correct relative paths.

* docs: add numeric prefixes to directories and files for navigation order

Add numeric prefixes (01-08) to documentation directories to indicate
reading order and flow for first-time users:

- 01-getting-started: Quick start guides
- 02-setup: Setup and configuration
- 03-production: Production deployment
- 04-operations: Site operations
- 05-development: Development guides
- 06-migration: Migration guides
- 07-troubleshooting: Troubleshooting
- 08-reference: Reference documentation

Add numeric prefixes to files within directories to guide readers
through documentation in a logical sequence.

Update all cross-references throughout documentation to use new
numbered paths. Update README.md to reflect the new structure.

* 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/.

* docs: remove container-setup subfolder and flatten structure

Move all files from docs/02-setup/container-setup/ directly into docs/02-setup/
to eliminate unnecessary subfolder. Files are already numbered sequentially,
so they work perfectly at the same level.

Changes:
- Move all files from container-setup/ subfolder to 02-setup/ root
- Remove container-setup/ subfolder
- Update all cross-references:
  - Update README.md paths (remove container-setup/ from all links)
  - Fix references in site-operations.md
  - Fix references in migration docs
  - Update internal references in 06-setup-examples.md
  - Fix relative path references in 01-overview.md, 02-build-setup.md, 03-start-setup.md

Result: Cleaner, flatter structure with all numbered setup files at the
same level, making navigation more straightforward.

* fix: Pre-commit failure is fixed

---------

Co-authored-by: adithya <adithya.a@bayesian.in>

README.md

@@ -55,32 +55,49 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose
 
 ### [Frequently Asked Questions](https://github.com/frappe/frappe_docker/wiki/Frequently-Asked-Questions)
 
+### [Getting Started](#getting-started)
+
+- [Quick Start (Linux/Mac)](docs/01-getting-started/01-quick-start-linux-mac.md)
+- [Single Compose Setup](docs/01-getting-started/02-single-compose-setup.md)
+
+### [Setup](#setup)
+
+- [Container Setup Overview](docs/02-setup/01-overview.md)
+- [Build Setup](docs/02-setup/02-build-setup.md)
+- [Start Setup](docs/02-setup/03-start-setup.md)
+- [Environment Variables](docs/02-setup/04-env-variables.md)
+- [Compose Overrides](docs/02-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)
 
-- [List of containers](docs/container-setup/01-overview.md)
+- [TLS/SSL Setup](docs/03-production/01-tls-ssl-setup.md)
-- [Single Compose Setup](docs/single-compose-setup.md)
+- [Backup Strategy](docs/03-production/02-backup-strategy.md)
-- [Environment Variables](docs/container-setup/env-variables.md)
+- [Multi-Tenancy](docs/03-production/03-multi-tenancy.md)
-- [Single Server Example](docs/single-server-example.md)
-- [Setup Options](docs/setup-options.md)
-- [Site Operations](docs/site-operations.md)
-- [Backup and Push Cron Job](docs/backup-and-push-cronjob.md)
-- [Port Based Multi Tenancy](docs/port-based-multi-tenancy.md)
-- [Migrate from multi-image setup](docs/migrate-from-multi-image-setup.md)
-- [running on linux/mac](docs/setup_for_linux_mac.md)
-- [TLS for local deployment](docs/tls-for-local-deployment.md)
 
-### [Custom Images](#custom-images)
+### [Operations](#operations)
 
-- [Custom Apps](docs/container-setup/02-build-setup.md)
+- [Site Operations](docs/04-operations/01-site-operations.md)
-- [Build Version 10 Images](docs/build-version-10-images.md)
 
 ### [Development](#development)
 
-- [Development using containers](docs/development.md)
+- [Development Guide](docs/05-development/01-development.md)
-- [Bench Console and VSCode Debugger](docs/bench-console-and-vscode-debugger.md)
+- [Debugging](docs/05-development/02-debugging.md)
-- [Connect to localhost services](docs/connect-to-localhost-services-from-containers-for-local-app-development.md)
+- [Local Services Connection](docs/05-development/03-local-services-connection.md)
 
-### [Troubleshoot](docs/troubleshoot.md)
+### [Migration](#migration)
+
+- [Migrate from Multi-Image Setup](docs/06-migration/01-migrate-from-multi-image-setup.md)
+
+### [Troubleshooting](#troubleshooting)
+
+- [Troubleshoot Guide](docs/07-troubleshooting/01-troubleshoot.md)
+- [Windows Nginx Entrypoint Error](docs/07-troubleshooting/02-windows-nginx-entrypoint-error.md)
+
+### [Reference](#reference)
+
+- [Build Version 10 Images](docs/08-reference/01-build-version-10-images.md)
 
 # Contributing
 

docs/02-setup/01-overview.md

@@ -40,8 +40,10 @@ Once images are built, containers are orchestrated using a [compose file](https:
 
 Additional functionality can be added using [overrides](https://docs.docker.com/compose/extends/). These files modify existing services or add new ones without changing the main `compose.yaml`.
 
-Example: The main compose file has no database service, but `compose.mariadb.yaml` adds MariaDB. See [overrider.md](overrider.md) for the complete list of available overrides and how to use them.
+Example: The main compose file has no database service, but `compose.mariadb.yaml` adds MariaDB. See [overrides.md](05-overrides.md) for the complete list of available overrides and how to use them.
 
 ---
 
 **Next:** [Build Setup →](02-build-setup.md)
+
+**See also:** [Setup Examples](06-setup-examples.md) for practical deployment scenarios.

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

@@ -95,7 +95,7 @@ The compose file requires several environment variables. You can either export t
 cp example.env custom.env
 ```
 
-Edit `custom.env` to customize variables for your setup. The template includes common variables, but you can add, modify, or remove any as needed. See [env-variables.md](env-variables.md) for detailed descriptions of all available variables.
+Edit `custom.env` to customize variables for your setup. The template includes common variables, but you can add, modify, or remove any as needed. See [env-variables.md](04-env-variables.md) for detailed descriptions of all available variables.
 
 # Creating the final compose file
 
@@ -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/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/02-setup/06-setup-examples.md

@@ -0,0 +1,138 @@
+# Setup Examples
+
+This guide provides practical examples for common setup scenarios. These examples build upon the [container setup guide](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](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](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 →](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.
 
@@ -285,4 +287,8 @@ docker compose --project-name custom-one-example -f ~/gitops/custom-one-example.
 
 ### Site operations
 
-Refer: [site operations](./site-operations.md)
+Refer: [site operations](../04-operations/01-site-operations.md)
+
+---
+
+**Back:** [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](images-and-compose-files.md#overrides)) 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/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/05-development/01-development.md

@@ -14,9 +14,9 @@ It is recommended you allocate at least 4GB of RAM to docker:
 - [Instructions for macOS](https://docs.docker.com/desktop/settings/mac/#advanced)
 
 Here is a screenshot showing the relevant setting in the Help Manual
-![image](images/Docker%20Manual%20Screenshot%20-%20Resources%20section.png)
+![image](../images/Docker%20Manual%20Screenshot%20-%20Resources%20section.png)
 Here is a screenshot showing the settings in Docker Desktop on Mac
-![images](images/Docker%20Desktop%20Screenshot%20-%20Resources%20section.png)
+![images](../images/Docker%20Desktop%20Screenshot%20-%20Resources%20section.png)
 
 ## Bootstrap Containers for development
 

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](environment-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/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.
 

docs/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](./environment-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](./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](./site-operations.md#migrate-site)