Merge pull request #1805 from adithyaappu/docs/vitepress-docs

Docs/vitepress docs

.github/workflows/publish_docs.yml

@@ -0,0 +1,60 @@
+name: Deploy Frappe Docker Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/publish_docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+defaults:
+  run:
+    working-directory: ./docs
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [24]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+          cache-dependency-path: ./docs
+
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+
+      - name: Build Docs site
+        run: pnpm docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/.vitepress/dist
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -28,3 +28,7 @@ venv
 
 # NodeJS
 node_modules
+
+# VitePress
+**/.vitepress/dist
+**/.vitepress/cache

.pre-commit-config.yaml

@@ -34,6 +34,7 @@ repos:
     rev: v2.4.1
     hooks:
       - id: codespell
+        exclude: ^docs/pnpm-lock\.yaml$
         args:
           - -L
           - "ro"

CONTRIBUTING.md

@@ -100,9 +100,35 @@ Run pytest:
 pytest
 ```
 
+## Detailed Guidelines
+
+A detailed form management guidelines are available in the [Fork Management](./docs/08-reference/03-fork-management.md)
+
 # Documentation
 
-Place relevant markdown files in the `docs` directory and index them in README.md located at the root of repo.
+Documentation is written as markdown files, and placed inside the `docs/` directory. There are multiple sub directories under `docs/`, and be sure to place the `.md` file in the relevant sub directory if you are adding a new page.
+
+If you want to include any image in the markdown file, place them in the `docs/images/` folder, and add a relative link in the `.md` file. For example if there is a `diagram.png` in the `docs/images/` directory, which has to be shown in a markdown file called `docs/01-getting-started/01-choosing-a-deployment-method.md` the image has to be referenced as,
+
+```
+![A diagram](../images/diagram.png)
+```
+
+Frappe Docker also have a static site version of the documentation, which is made using the same `.md` files in the `docs/` directory. Build pipeline uses [VitePress](https://vitepress.dev/) as the Static Site builder, which is a JavaScript (TypeScript) static site builder. Note that to contribute to the documentation JavaScript or VitePress knowledge is not needed. Updating the `.md` file is enough.
+
+The only additional content needed that is specific to VitePress, is a ['frontmatter'](https://vitepress.dev/guide/frontmatter#frontmatter). Frontmatter is like the `metadata` or `config` of that specific `.md` file, added at the beginning of the file and enclosed in `---`. For example, the frontmatter can include a friendly title, author, date of publishing, etc. A more detailed overview on what is frontmatter can be found in this [blog](https://www.seancdavis.com/posts/wtf-is-frontmatter/).
+
+In this project only one field is used in the frontmatter. The `title` field. This is used to specify the title of the page shown in the sidebar, which is either same or a simpler and smaller version of the first heading `#` of the page. To add the required frontmatter just add a block at the beginning of the `.md` file as shown below
+
+```yaml
+---
+title: <short-title-for-sidebar>
+---
+```
+
+In case of any doubt, just refer to any of the existing `.md` file. Also checkout the Markdown section in the VitePress documentation to see some additional features supported by VitePress: [Markdown Extensions](https://vitepress.dev/guide/markdown). Be careful not to break compatibility with what is supported by GitHub markdown. It is recommended to keep the documentation simple.
+
+If you want details on how to configure or update VitePress specific settings and and functionalities, refer this page: [Configuring VitePress](https://github.com/frappe/frappe_docker/blob/main/docs/08-reference/02-configuring-vitepress.md)
 
 # Frappe and ERPNext updates
 

docs/.vitepress/config.mts

@@ -0,0 +1,29 @@
+import { defineConfig, UserConfig } from "vitepress";
+import { withSidebar } from "vitepress-sidebar";
+
+// https://vitepress.dev/reference/site-config
+const vitePressOptions: UserConfig = {
+  title: "Frappe Docker Docs",
+  description: "Frappe in a Container",
+  base: "/frappe_docker/",
+  head: [["link", { rel: "icon", href: "/frappe_docker/favicon.png" }]],
+  themeConfig: {
+    logo: "/frappe-docker.png",
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [{ text: "Home", link: "/" }],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/frappe/frappe_docker/" },
+    ],
+  },
+};
+
+const vitePressSidebarOptions = {
+  documentRootPath: ".",
+  useTitleFromFrontmatter: true,
+  useFolderTitleFromIndexFile: true,
+};
+
+export default defineConfig(
+  withSidebar(vitePressOptions, vitePressSidebarOptions),
+);

docs/01-getting-started/00-introduction.md

@@ -0,0 +1,92 @@
+---
+title: Introduction
+---
+
+# Introduction to Frappe Docker
+
+This is the documentation for the Frappe Docker repository, which contains all the information on how to develop, deploy and share Frappe app, using Docker containers.
+
+## Repository Architecture
+
+Frappe Docker provides a comprehensive containerized environment for developing and deploying Frappe/ERPNext applications. It uses a **multi-service architecture** that handles everything from web serving to background job processing.
+
+### Core Services
+
+The base compose file includes these essential services:
+
+- **configurator** - Initialization service that configures database and Redis connections; runs on startup and exits
+- **backend** - Werkzeug development server for dynamic content processing
+- **frontend** - Nginx reverse proxy that serves static assets and routes requests
+- **websocket** - Node.js server running Socket.IO for real-time communications
+- **queue-short/long** - Python workers using RQ (Redis Queue) for asynchronous background job processing
+- **scheduler** - Python service that runs scheduled tasks using the schedule library
+
+Additional services are added through compose overrides:
+
+- **db** - MariaDB or PostgreSQL database server (via `compose.mariadb.yaml` or `compose.postgres.yaml`)
+- **redis-cache/queue** - Redis instances for caching and job queues (via `compose.redis.yaml`)
+
+### How Services Work Together
+
+```
+User Request
+    ↓
+[frontend (Nginx)] → Static files served directly
+    ↓
+[backend (Werkzeug)] → Dynamic content processing
+    ↓                    ↓
+[db (MariaDB)]      [redis-cache]
+
+Background Tasks:
+[scheduler] → [redis-queue] → [queue-short/long workers]
+
+Real-time:
+[websocket (Socket.IO)] ←→ [redis-cache]
+```
+
+## Repository Structure
+
+### `/` Root: Core Configuration Files
+
+- **compose.yaml** - Main Docker Compose file defining all services
+- **example.env** - Environment variables template (copy to `.env`)
+- **pwd.yml** - "Play with Docker" - simplified single-file setup for quick testing
+- **docker-bake.hcl** - Advanced Docker Buildx configuration for multi-architecture builds
+- **docs/container-setup/env-variables.md** - Central reference for environment configuration logic and defaults
+
+### `images/`: Docker Image Definitions
+
+Four predefined Dockerfiles are available, each serving different use cases:
+
+- **images/bench/** - Sets up only the Bench CLI for development or debugging; does not include runtime services
+- **images/custom/** - Multi-purpose Python backend built from plain Python base image; installs apps from `apps.json`; suitable for **production** and testing; ideal when you need control over Python/Node versions
+- **images/layered/** - Same final contents as `custom` but based on prebuilt images from Docker Hub; faster builds for production when using Frappe-managed dependency versions
+- **images/production/** - Installs only Frappe and ERPNext (not customizable with `apps.json`); best for **quick starts or exploration**; for real deployments, use `custom` or `layered`
+
+> **Note:** For detailed build arguments and advanced configuration options, see [Setup Overview](../02-setup/01-overview.md).
+
+### `overrides/`: Compose File Extensions
+
+Docker Compose "overrides" that extend the base compose.yaml for different scenarios:
+
+- **compose.mariadb.yaml** - Adds MariaDB database service
+- **compose.redis.yaml** - Adds Redis caching service
+- **compose.proxy.yaml** - Adds Traefik reverse proxy for multi-site hosting (label-based routing)
+- **compose.https.yaml** - Adds Traefik HTTPS + automatic certs (uses `SITES_RULE`)
+- **compose.nginxproxy.yaml** - Adds nginx-proxy reverse proxy (HTTP, env-based `VIRTUAL_HOST`)
+- **compose.nginxproxy-ssl.yaml** - Adds nginx-proxy + acme-companion (HTTPS, env-based `LETSENCRYPT_HOST`)
+
+**Proxy choice:**
+
+- Traefik is more flexible for advanced routing and multi-bench setups
+- nginx-proxy is simpler for a single bench with host-based routing.
+
+### `development/`: Dev Environment
+
+- **development/installer.py** - Automated bench/site creation and configuration script
+- Contains your local development files (git-ignored to prevent accidental commits)
+
+### `resources/`: Runtime Templates
+
+- **core/nginx/nginx-entrypoint.sh** - Dynamic Nginx configuration generator script
+- **core/nginx/nginx-template.conf** - Nginx configuration template with variable substitution

docs/01-getting-started/01-choosing-a-deployment-method.md

@@ -1,3 +1,7 @@
+---
+title: Choosing a Method
+---
+
 # Choosing a Deployment or Development Method
 
 This repository (`frappe_docker`) supports **multiple ways to run Frappe using Docker**.
@@ -45,7 +49,7 @@ If you start with `pwd.yml`, you should expect to **throw the environment away**
 
 ## 2. VS Code Devcontainers – Local Development Setup
 
-The development setup described in [`/docs/05-development`](../05-development)
+The development setup described in [`/docs/05-development/development.md`](../05-development/01-development.md)
 
 uses **VS Code Devcontainers** to provide a **local Frappe development environment**.
 
@@ -103,7 +107,7 @@ It uses:
 - The main `compose.yml`
 - Override files from the `overrides/` directory
 
-Detailed instructions are available in [`/docs/02-setup`](../02-setup)
+Detailed instructions are available in [`/docs/02-setup`](../02-setup/01-overview.md)
 
 ### Characteristics
 

docs/01-getting-started/02-docker-immutability.md

@@ -1,3 +1,7 @@
+---
+title: Docker Immutability
+---
+
 # Important Concept: Immutability and Persistence
 
 A frequent source of confusion is how **Docker-based Frappe deployments handle persistence**.

docs/01-getting-started/03-arm64.md

@@ -1,3 +1,7 @@
+---
+title: Quick Start with Linux and Mac
+---
+
 # How to install ERPNext on linux/mac using Frappe_docker ?
 
 ## Clone the repo

docs/01-getting-started/04-single-compose-setup.md

@@ -1,3 +1,7 @@
+---
+title: Single Compose Setup
+---
+
 # Single Compose Setup
 
 This setup is a very simple single compose file that does everything to start required services and a frappe-bench. It is used to start play with docker instance with a site. The file is located in the root of repo and named `pwd.yml`.

docs/01-getting-started/index.md

@@ -0,0 +1,3 @@
+---
+title: Getting Started
+---

docs/02-setup/01-overview.md

@@ -1,3 +1,7 @@
+---
+title: Setup Overview
+---
+
 The purpose of this document is to give you an overview of how the Frappe Docker containers are structured.
 
 # 🐳 Images

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

@@ -1,3 +1,7 @@
+---
+title: Build Setup
+---
+
 This guide walks you through building Frappe images from the repository resources.
 
 # Prerequisites

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

@@ -1,3 +1,7 @@
+---
+title: Start Container
+---
+
 # start Container
 
 Once your compose file is ready, start all containers with a single command:

docs/02-setup/04-env-variables.md

@@ -1,3 +1,7 @@
+---
+title: Environment Variables
+---
+
 # Environment Variables Reference
 
 Environment variables configure your Frappe Docker setup. They can be set directly in the container or defined in a `.env` file referenced by Docker Compose.

docs/02-setup/05-overrides.md

@@ -1,3 +1,7 @@
+---
+title: Overrides
+---
+
 Overrides extend the base compose.yaml with additional services or modify existing behavior. Include them in your compose command using multiple -f flags.
 
 ```bash

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

@@ -1,3 +1,7 @@
+---
+title: Setup Examples
+---
+
 # 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.

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

@@ -1,3 +1,7 @@
+---
+title: Single Server Setup
+---
+
 # Single Server Example
 
 This guide demonstrates setting up multiple Frappe/ERPNext benches (projects) on a single server with shared infrastructure components.

docs/02-setup/08-single-server-nginxproxy-example.md

@@ -1,3 +1,7 @@
+---
+title: Single Server Example
+---
+
 # Single Server Example (nginx-proxy + acme-companion)
 
 This guide demonstrates a single-server setup using nginx-proxy and acme-companion for HTTPS. It is best for a small number of hostnames and a single bench. If you need multiple benches or advanced routing, use the Traefik-based example instead.

docs/02-setup/index.md

@@ -0,0 +1,3 @@
+---
+title: Setup
+---

docs/03-production/01-tls-ssl-setup.md

@@ -1,3 +1,7 @@
+---
+title: TLS/SSL Setup Overview
+---
+
 # TLS/SSL Setup Overview
 
 Frappe Docker supports multiple TLS/SSL approaches. Choose the one that matches your routing needs and where you want the proxy to run.

docs/03-production/02-backup-strategy.md

@@ -1,3 +1,7 @@
+---
+title: Backup Strategy
+---
+
 Create backup service or stack.
 
 ```yaml

docs/03-production/03-multi-tenancy.md

@@ -1,3 +1,7 @@
+---
+title: Multi Tenancy
+---
+
 WARNING: Do not use this in production if the site is going to be served over plain http.
 
 ### Step 1

docs/03-production/04-nginx-proxy-acme-companion.md

@@ -1,3 +1,7 @@
+---
+title: NGINX and ACME Companion
+---
+
 # nginx-proxy + acme-companion (HTTPS)
 
 This guide explains how to use nginx-proxy with acme-companion to provide HTTPS for a Frappe Docker stack.

docs/03-production/05-caddy-https.md

@@ -1,3 +1,7 @@
+---
+title: Caddy with HTTPS
+---
+
 # Caddy reverse proxy (local HTTPS)
 
 This guide shows how to use Caddy as an external reverse proxy in front of the frontend container. It is most useful for local HTTPS or internal networks.

docs/03-production/index.md

@@ -0,0 +1,3 @@
+---
+title: Production
+---

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

@@ -1,3 +1,7 @@
+---
+title: Site Operations
+---
+
 # Site operations
 
 > 💡 You should setup `--project-name` option in `docker-compose` commands if you have non-standard project name.

docs/04-operations/index.md

@@ -0,0 +1,3 @@
+---
+title: Operations
+---

docs/05-development/01-development.md

@@ -1,3 +1,7 @@
+---
+title: Getting Started
+---
+
 # Getting Started
 
 ## Prerequisites
@@ -97,6 +101,26 @@ PYENV_VERSION=3.9.17 bench init --skip-redis-config-generation --frappe-branch v
 cd frappe-bench
 ```
 
+At this point the the directory structure will be very close to this, if not exact,
+
+```
+development/
+├── frappe-bench/           # Your actual Frappe installation
+│   ├── apps/              # All installed Frappe applications
+│   │   ├── frappe/        # Core framework (don't modify directly)
+│   │   ├── erpnext/       # ERPNext application (if installed)
+│   │   └── my_custom_app/ # Your custom apps (edit freely)
+│   ├── sites/             # Multi-tenant sites
+│   │   ├── development.localhost/     # Default dev site
+│   │   │   ├── site_config.json      # Site-specific config
+│   │   │   └── private/files/        # Uploaded files
+│   │   └── common_site_config.json   # Shared configuration
+│   ├── env/               # Python virtual environment
+│   ├── logs/              # Application logs
+│   └── config/            # Bench-level configuration
+└── .vscode/               # VSCode workspace settings
+```
+
 ### Setup hosts
 
 We need to tell bench to use the right containers instead of localhost. Run the following commands inside the container:

docs/05-development/02-debugging.md

@@ -1,3 +1,7 @@
+---
+title: Debugging
+---
+
 Add the following configuration to `launch.json` `configurations` array to start bench console and use debugger. Replace `development.localhost` with appropriate site. Also replace `frappe-bench` with name of the bench directory.
 
 ```json

docs/05-development/03-local-services-connection.md

@@ -1,3 +1,7 @@
+---
+title: Local Services
+---
+
 Add following to frappe container from the `.devcontainer/docker-compose.yml`:
 
 ```yaml

docs/05-development/index.md

@@ -0,0 +1,3 @@
+---
+title: Development
+---

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

@@ -1,3 +1,7 @@
+---
+title: Migrate from Multi Image Setup
+---
+
 ## Migrate from multi-image setup
 
 All the containers now use same image. Use `frappe/erpnext` instead of `frappe/frappe-worker`, `frappe/frappe-nginx` , `frappe/frappe-socketio` , `frappe/erpnext-worker` and `frappe/erpnext-nginx`.

docs/06-migration/02-traefik-v3-migration.md

@@ -1,3 +1,7 @@
+---
+title: Migrate Traefik from v2 to v3
+---
+
 # Migrate an existing Traefik v2 instance to v3
 
 Use this guide if you already run Traefik v2 with `frappe_docker` and want to upgrade to v3. It focuses on the image upgrade and the v3 routing rule changes that affect existing setups.

docs/06-migration/index.md

@@ -0,0 +1,3 @@
+---
+title: Migration
+---

docs/07-troubleshooting/01-troubleshoot.md

@@ -1,6 +1,11 @@
-1. [Fixing MariaDB issues after rebuilding the container](#fixing-mariadb-issues-after-rebuilding-the-container)
-1. [docker-compose does not recognize variables from `.env` file](#docker-compose-does-not-recognize-variables-from-env-file)
-1. [Windows Based Installation](#windows-based-installation)
+---
+title: Troubleshoot
+---
+
+- [Fixing MariaDB issues after rebuilding the container](#fixing-mariadb-issues-after-rebuilding-the-container)
+- [docker-compose does not recognize variables from `.env` file](#docker-compose-does-not-recognize-variables-from-env-file)
+- [Windows Based Installation](#windows-based-installation)
+- [Redo installation](#redo-installation)
 
 ### Fixing MariaDB issues after rebuilding the container
 

docs/07-troubleshooting/02-windows-nginx-entrypoint-error.md

@@ -1,3 +1,7 @@
+---
+title: NGINX in Windows
+---
+
 # Resolving Docker `nginx-entrypoint.sh` Script Not Found Error on Windows
 
 If you're encountering the error `exec /usr/local/bin/nginx-entrypoint.sh: no such file or directory` in a Docker container on Windows, follow these steps to resolve the issue.

docs/07-troubleshooting/03-arm64-apple-silicon.md

@@ -0,0 +1,10 @@
+---
+title: ARM64 / Apple Silicon
+---
+
+## Notes on ARM64 and Apple Silicon
+
+- Enable Docker Desktop's Rosetta emulation for initial builds when running on Apple Silicon with x86-only images.
+- Prefer published multi-arch images (`frappe/bench`, `frappe/erpnext`) or build locally with `docker buildx bake --set *.platform=linux/amd64,linux/arm64` to cover both architectures in one pass.
+- When using `pwd.yml`, export `DOCKER_DEFAULT_PLATFORM=linux/arm64` (or select the provided compose profile) to avoid unexpected emulation.
+- Keep bind mounts under your user home directory and apply `:cached` or `:delegated` consistency flags for better performance on macOS.

docs/07-troubleshooting/index.md

@@ -0,0 +1,3 @@
+---
+title: Troubleshooting
+---

docs/08-reference/01-build-version-10-images.md

@@ -1,3 +1,7 @@
+---
+title: Build Version 10
+---
+
 Clone the version-10 branch of this repo
 
 ```shell

docs/08-reference/02-configuring-vitepress.md

@@ -0,0 +1,45 @@
+---
+title: Configuring VitePress
+---
+
+# Configuring VitePress
+
+To modify any VitePress related settings, a JavaScript development environment is needed. Everything related to VitePress is contained in the `docs/` folder.
+
+## Prerequisites
+
+1. Node.js v24 or above is recommended. To install and manage Node.js [nvm](https://github.com/nvm-sh/nvm) is the preferred way for Linux and MacOS. For Windows either official installer or [fnm](https://github.com/Schniz/fnm).
+2. pnpm package manager, v10.28 or above. Easiest way to install pnpm is using [corepack](https://pnpm.io/installation#using-corepack) which is part of Node.js.
+
+## Development
+
+To start a development environment,
+
+1. Navigate to `/docs` directory in the terminal
+
+```sh
+cd docs
+```
+
+2. Install dependencies
+
+```sh
+pnpm install
+```
+
+3. Start the development server
+
+```sh
+pnpm run docs:dev
+```
+
+4. Open `http://localhost:5173/frappe_docker` in your browser to see the development version which will update the preview as you make changes.
+
+## Configurations
+
+1. Public assets related to VitePress site is added in the `docs/public` folder. This folder should **NOT** be used for adding images added inside the `.md` file.
+2. VitePress uses `index.md` files to do some special things. For example the home page is configured using the `docs/index.md` file. Checkout the file for more details.
+3. VitePress uses 'file based routing', meaning the URL paths mimics the directory and file structure inside the `docs/` directory.
+4. VitePress specific config is `docs/.vitepress/config.mts`.
+5. To auto populate the sidebar, a plugin called 'VitePress Sidebar' is used. The `config.mts` also include config for this plugin. More details can be found in the [documentation page](https://vitepress-sidebar.cdget.com/guide/getting-started).
+6. Each subfolder has an `index.md` file. This is used to specify the group heading of the pages in the sidebar.

docs/08-reference/03-fork-management.md

@@ -0,0 +1,161 @@
+---
+title: Fork Management
+---
+
+# Fork Management Best Practices
+
+## Initial Fork Setup
+
+```bash
+# 1. Fork on GitHub (use the Fork button)
+
+# 2. Clone YOUR fork
+git clone https://github.com/YOUR_USERNAME/frappe_docker
+cd frappe_docker
+
+# 3. Add upstream remote (original repo)
+git remote add upstream https://github.com/frappe/frappe_docker.git
+
+# 4. Verify remotes
+git remote -v
+# origin    https://github.com/YOUR_USERNAME/frappe_docker (your fork)
+# upstream  https://github.com/frappe/frappe_docker (original)
+
+# 5. Create development branch
+git checkout -b my-custom-setup
+```
+
+## Safe Customization Zones
+
+**✅ Safe (Won't conflict with upstream):**
+
+```
+development/                    # Your entire dev environment
+  ├── frappe-bench/            # Local installation
+  └── .vscode/                 # Your editor settings
+
+compose.my-*.yaml              # Your custom compose overrides
+scripts/my-*.sh                # Your custom scripts
+docs/my-*.md                   # Your custom documentation
+.env.local                     # Local environment overrides
+.gitignore.local              # Additional gitignore rules
+```
+
+**⚠️ Modification Needed (May conflict):**
+
+```
+compose.yaml                   # Core - use overrides instead
+docker-bake.hcl               # Build config - use custom files
+images/*/Dockerfile           # Core images - extend rather than modify
+```
+
+**❌ Never Modify (Will break upstream sync):**
+
+```
+.github/workflows/            # CI/CD pipelines
+images/*/                     # Core image definitions
+resources/                    # Core templates
+```
+
+## Keeping Fork Updated
+
+```bash
+# Regularly sync with upstream (weekly recommended)
+git checkout main
+git fetch upstream
+git merge upstream/main
+git push origin main
+
+# Update your development branch
+git checkout my-custom-setup
+git rebase main  # Or: git merge main
+
+# If conflicts occur during rebase:
+# 1. Fix conflicts in files
+# 2. git add <fixed-files>
+# 3. git rebase --continue
+# Or: git rebase --abort  (to cancel)
+```
+
+## Custom Environment Pattern
+
+Create override files for your customizations:
+
+```yaml
+# compose.my-env.yaml
+version: "3.7"
+
+services:
+  backend:
+    environment:
+      # Your custom environment variables
+      - DEVELOPER_MODE=true
+      - MY_API_KEY=${MY_API_KEY}
+    volumes:
+      # Your custom bind mounts
+      - ./development/my-scripts:/home/frappe/my-scripts
+      - ./development/my-config:/home/frappe/config
+
+  # Your additional services
+  my-monitoring:
+    image: prom/prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
+# Use it:
+# docker compose -f compose.yaml -f compose.my-env.yaml up
+```
+
+## .gitignore Strategy
+
+Add to `.gitignore` (or create `.gitignore.local`):
+
+```gitignore
+# Local environment files
+.env.local
+*.local.yaml
+compose.my-*.yaml
+
+# Development artifacts
+development/frappe-bench/sites/*
+development/frappe-bench/apps/*
+!development/frappe-bench/apps.json
+development/frappe-bench/logs/
+development/frappe-bench/env/
+
+# Local customizations
+my-local-configs/
+scripts/my-*.sh
+docs/internal-*.md
+
+# IDE
+.vscode/settings.json.local
+.idea/
+
+# Temporary files
+*.swp
+*.swo
+*~
+.DS_Store
+```
+
+## Contributing Back to Upstream
+
+```bash
+# 1. Create feature branch from main
+git checkout main
+git pull upstream main
+git checkout -b feature/my-improvement
+
+# 2. Make changes and commit
+git add .
+git commit -m "feat: add awesome feature"
+
+# 3. Push to YOUR fork
+git push origin feature/my-improvement
+
+# 4. Create Pull Request on GitHub
+# Go to: https://github.com/frappe/frappe_docker
+# Click "Compare & pull request"
+```

docs/08-reference/04-framework-comparisons.md

@@ -0,0 +1,163 @@
+---
+title: Framework Comparisons
+---
+
+# Framework Comparisons
+
+> **Note:** This section provides comparisons to other frameworks for developers familiar with them. If you're new to all frameworks, you can skip this section - the rest of the guide is self-contained.
+
+## Frappe vs Django Concepts
+
+### Project Structure Comparison
+
+**Django Project:**
+
+```python
+myproject/
+├── myproject/          # Project settings
+│   ├── settings.py
+│   ├── urls.py
+│   └── wsgi.py
+├── blog/              # Django app
+│   ├── models.py
+│   ├── views.py
+│   └── urls.py
+├── shop/              # Django app
+└── users/             # Django app
+```
+
+**Frappe Bench:**
+
+```
+bench/
+├── apps/
+│   ├── frappe/        # Core framework (comparable to Django itself)
+│   ├── erpnext/       # Complete business app (like Django + DRF + Celery + admin)
+│   ├── hrms/          # HR Management app
+│   └── my_custom_app/ # YOUR custom app
+└── sites/
+    └── mysite.com/    # Site instance (like Django project + database)
+        ├── site_config.json
+        └── private/files/
+```
+
+### Conceptual Mapping
+
+| Django             | Frappe            | Notes                                           |
+| ------------------ | ----------------- | ----------------------------------------------- |
+| Model              | DocType           | But includes UI, permissions, API automatically |
+| View               | Controller method | Much less code needed                           |
+| Admin              | Desk              | More powerful, auto-generated                   |
+| DRF Serializer     | Built-in          | Automatic from DocType                          |
+| Celery task        | Background job    | Built-in, no separate setup                     |
+| signals            | hooks.py          | More structured                                 |
+| Management command | bench command     | More discoverable                               |
+
+### Key Architectural Differences
+
+1. **Multi-tenancy**
+
+   - Django: One app = one database (typically)
+   - Frappe: One installation = many sites, each with own database
+
+2. **Background Jobs**
+
+   - Django: Requires Celery + Redis + worker setup
+   - Frappe: Built-in queue system, just use `enqueue()`
+
+3. **Real-time**
+
+   - Django: Requires Channels + Redis + ASGI setup
+   - Frappe: Socket.IO built-in, automatic for DocType updates
+
+4. **Admin/Management**
+
+   - Django: Admin for models, basic CRUD
+   - Frappe: Full-featured Desk with reports, dashboards, permissions
+
+5. **API**
+   - Django: Manual DRF setup, serializers, views
+   - Frappe: Automatic REST + RPC from DocType definitions
+
+### Code Comparison Example
+
+**Creating a "Customer" model:**
+
+Django (requires ~50+ lines):
+
+```python
+# models.py
+class Customer(models.Model):
+    name = models.CharField(max_length=100)
+    email = models.EmailField(unique=True)
+
+# serializers.py
+class CustomerSerializer(serializers.ModelSerializer):
+    # ...
+
+# views.py
+class CustomerViewSet(viewsets.ModelViewSet):
+    # ...
+
+# urls.py
+router.register(r'customers', CustomerViewSet)
+
+# admin.py
+@admin.register(Customer)
+class CustomerAdmin(admin.ModelAdmin):
+    # ...
+```
+
+Frappe (DocType JSON + ~10 lines Python):
+
+```json
+// customer.json (auto-generated via UI or code)
+{
+  "name": "Customer",
+  "fields": [
+    { "fieldname": "customer_name", "fieldtype": "Data" },
+    { "fieldname": "email", "fieldtype": "Data", "unique": 1 }
+  ]
+}
+```
+
+```python
+# customer.py (only for custom business logic)
+import frappe
+from frappe.model.document import Document
+
+class Customer(Document):
+    def validate(self):
+        # Custom validation logic only
+        pass
+```
+
+✅ **Automatically includes:**
+
+- REST API (`/api/resource/Customer`)
+- List view, Form view
+- Search, Filters, Sorting
+- Permissions (Create, Read, Update, Delete)
+- Audit trail (created_by, modified_by, versions)
+- Print formats, Email templates
+
+### When to Choose Frappe vs Django
+
+**Choose Frappe when:**
+
+- Building business applications (ERP, CRM, project management)
+- Need multi-tenancy out-of-the-box
+- Want rapid development with auto-generated UI
+- Need role-based permissions and workflows
+- Building for non-technical users who need customization
+
+**Choose Django when:**
+
+- Building consumer web apps (social media, e-commerce frontend)
+- Need full control over every aspect
+- Have highly custom UI requirements
+- Team is already Django-expert
+- Building API-only services
+
+**Hybrid Approach:**
+Many teams use both: Frappe for back-office/admin tools, Django for customer-facing web apps.

docs/08-reference/05-external-links.md

@@ -0,0 +1,18 @@
+---
+title: External Links
+---
+
+# External Links
+
+## Official Documentation
+
+- [Frappe Framework Docs](https://frappeframework.com/docs) - Core framework documentation
+- [Frappe Docker Docs](https://github.com/frappe/frappe_docker/tree/main/docs) - This repository's docs
+- [ERPNext Documentation](https://docs.erpnext.com) - ERPNext user and developer docs
+- [Docker Documentation](https://docs.docker.com) - Docker fundamentals
+
+## Community Resources
+
+- [Frappe Forum](https://discuss.frappe.io) - Community Q&A
+- [Frappe School](https://frappe.school) - Video tutorials
+- [Frappe GitHub](https://github.com/frappe/frappe) - Framework source code

docs/08-reference/index.md

@@ -0,0 +1,3 @@
+---
+title: References
+---

docs/09-concepts/01-custom-app.md

@@ -0,0 +1,64 @@
+---
+title: Custom Apps
+---
+
+# Frappe Custom Applications
+
+## What Are Frappe Custom Apps?
+
+Custom apps are self-contained, modular business applications that extend Frappe's functionality. They follow a convention-over-configuration approach where the framework provides most boilerplate automatically.
+
+## Custom App Structure
+
+```
+my_custom_app/
+├── hooks.py                          # App configuration and hooks into Frappe lifecycle
+├── modules.txt                       # List of business modules in this app
+├── my_custom_app/
+│   ├── __init__.py
+│   ├── config/
+│   │   └── desktop.py                # Desktop workspace icons and shortcuts
+│   ├── my_module/                    # Business domain module (e.g., sales, inventory)
+│   │   ├── doctype/                  # Document Types (data models)
+│   │   │   ├── customer/
+│   │   │   │   ├── customer.py       # Python controller (business logic)
+│   │   │   │   ├── customer.json     # Model definition (schema, validation)
+│   │   │   │   └── customer.js       # Frontend logic (UI interactions)
+│   │   └── page/                     # Custom pages (dashboards, reports)
+│   ├── public/                       # Static assets (CSS, JS, images)
+│   ├── templates/                    # Jinja2 templates for web pages
+│   └── www/                          # Web pages accessible via routes
+└── requirements.txt                  # Python package dependencies
+```
+
+## Built-in Features (Auto-generated)
+
+Every Frappe app automatically includes:
+
+- **REST API** - Automatic CRUD endpoints from DocType definitions
+- **Permissions system** - Row-level and field-level access control
+- **Audit trails** - Automatic version tracking and change history
+- **Custom fields** - Runtime field additions without code changes
+- **Workflows** - Configurable approval and state management
+- **Reports** - Query builder and report designer
+- **Print formats** - PDF generation with custom templates
+- **Email integration** - Template-based email sending
+- **File attachments** - Document attachment management
+
+## Creating Custom Apps
+
+```bash
+# Enter the development container
+docker exec -it <container_name> bash
+
+# Create new app (interactive prompts will ask for details)
+bench new-app my_custom_app
+
+# Install app to a site
+bench --site mysite.com install-app my_custom_app
+
+# Create a new DocType (data model)
+bench --site mysite.com console
+>>> bench.new_doc("DocType", {...})
+# Or use the web UI: Setup → Customize → DocType → New
+```

docs/09-concepts/02-docker-bind-mounts.md

@@ -0,0 +1,62 @@
+---
+title: Docker Bind Mounts
+---
+
+# Docker Bind Mounts
+
+## What Are Bind Mounts?
+
+Bind mounts create a direct connection between a directory on your host machine and a directory inside a container. Changes in either location are immediately reflected in the other - perfect for development where you want to edit code on your host and see changes in the container.
+
+## Bind Mount vs Named Volume vs Anonymous Volume
+
+| Type                 | Syntax                         | Use Case                   | Persistence                  |
+| -------------------- | ------------------------------ | -------------------------- | ---------------------------- |
+| **Bind Mount**       | `./local/path:/container/path` | Development, config files  | On host filesystem           |
+| **Named Volume**     | `volume_name:/container/path`  | Production data, databases | Docker-managed               |
+| **Anonymous Volume** | `/container/path`              | Temporary/cache data       | Docker-managed, auto-deleted |
+
+## Bind Mount Examples
+
+```yaml
+services:
+  backend:
+    volumes:
+      # Development: Edit code on host, run in container
+      - ./my_custom_app:/home/frappe/frappe-bench/apps/my_custom_app
+
+      # Configuration: Override container config with host file
+      - ./custom-config.json:/home/frappe/frappe-bench/sites/common_site_config.json:ro # :ro = read-only
+
+      # Logs: Access container logs on host for debugging
+      - ./logs:/home/frappe/frappe-bench/logs
+
+      # Database (not recommended for production)
+      - ./data/mysql:/var/lib/mysql
+
+  # Named volume for production database
+  db:
+    volumes:
+      - db_data:/var/lib/mysql # Managed by Docker, survives container deletion
+
+volumes:
+  db_data: # Define named volume
+```
+
+## Performance Optimization (macOS/Windows)
+
+Docker on macOS/Windows uses a VM, making bind mounts slower. Use these flags:
+
+```yaml
+volumes:
+  # :cached - Host writes are buffered (good for general development)
+  - ./development:/home/frappe/frappe-bench:cached
+
+  # :delegated - Container writes are buffered (best when container writes heavily)
+  - ./development:/home/frappe/frappe-bench:delegated
+
+  # :consistent - Full synchronization (slowest but safest)
+  - ./development:/home/frappe/frappe-bench:consistent
+```
+
+**Recommendation:** Use `:cached` for most development work on macOS/Windows.

docs/09-concepts/index.md

@@ -0,0 +1,3 @@
+---
+title: Concepts
+---

docs/getting-started.md

@@ -1,3 +1,7 @@
+---
+title: Getting Started
+---
+
 # Getting Started with Frappe Docker
 
 _A comprehensive guide for developers getting started with Frappe Docker, with comparisons to Django for teams familiar with that framework_
@@ -85,7 +89,7 @@ Four predefined Dockerfiles are available, each serving different use cases:
 - **images/layered/** - Same final contents as `custom` but based on prebuilt images from Docker Hub; faster builds for production when using Frappe-managed dependency versions
 - **images/production/** - Installs only Frappe and ERPNext (not customizable with `apps.json`); best for **quick starts or exploration**; for real deployments, use `custom` or `layered`
 
-> **Note:** For detailed build arguments and advanced configuration options, see [docs/container-setup/01-overview.md](container-setup/01-overview.md).
+> **Note:** For detailed build arguments and advanced configuration options, see [docs/02-setup/01-overview.md](02-setup/01-overview.md).
 
 ### 📁 overrides/ - Compose File Extensions
 
@@ -855,11 +859,11 @@ Many teams use both: Frappe for back-office/admin tools, Django for customer-fac
 
 ### Key Files in This Repository
 
-- [`docs/development.md`](development.md) - Detailed development setup
-- [`docs/container-setup/env-variables.md`](container-setup/env-variables.md) - Environment variable reference
-- [`docs/single-server-example.md`](single-server-example.md) - Production deployment guide
-- [`docs/site-operations.md`](site-operations.md) - Common site management tasks
-- [`development/installer.py`](../development/installer.py) - Automated setup script
+- [`docs/05-development/01-development.md`](05-development/01-development.md) - Detailed development setup
+- [`docs/02-setup/04-env-variables.md`](02-setup/04-env-variables.md) - Environment variable reference
+- [`docs/02-setup/07-single-server-example.md`](02-setup/07-single-server-example.md) - Production deployment guide
+- [`docs/04-operations/01-site-operations.md`](04-operations/01-site-operations.md) - Common site management tasks
+- `development/installer.py` - Automated setup script
 - [`pwd.yml`](../pwd.yml) - Quick test configuration
 - [`compose.yaml`](../compose.yaml) - Base Docker Compose configuration
 
@@ -954,7 +958,7 @@ bench update                     # Update framework and apps
 
 ### Getting Help
 
-1. **Check existing docs** - Most issues covered in [`docs/troubleshoot.md`](troubleshoot.md)
+1. **Check existing docs** - Most issues covered in [`docs/07-troubleshooting/01-troubleshoot.md](07-troubleshooting/01-troubleshoot.md)
 2. **Search Frappe Forum** - [discuss.frappe.io](https://discuss.frappe.io)
 3. **GitHub Issues** - Search existing issues first
 4. **Discord/Telegram** - Community real-time chat (links in main repo)
@@ -965,7 +969,7 @@ Found issues or improvements for this guide?
 
 - Create an issue: [frappe_docker/issues](https://github.com/frappe/frappe_docker/issues)
 - Submit focused PRs: keep updates scoped and split large efforts across multiple pull requests.
-- Review [CONTRIBUTING.md](../CONTRIBUTING.md) for coding standards and review expectations.
+- Review CONTRIBUTING.md: for coding standards and review expectations.
 
 ---
 

docs/index.md

@@ -0,0 +1,26 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Frappe in Docker"
+  # text: "Frappe in Container"
+  tagline: "Documentation to use Docker based setup of Frappe framework"
+  image:
+    src: /frappe-docker.png
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started
+    - theme: alt
+      text: Single Compose Setup
+      link: /01-getting-started/02-single-compose-setup
+
+features:
+  - title: Containerised
+    details: All the power of Frappe, but in the container
+  - title: Setup in Minutes
+    details: Get it started in a few minutes
+  - title: Production Ready
+    details: Deploy production applications with ease
+---

docs/package.json

@@ -0,0 +1,12 @@
+{
+  "devDependencies": {
+    "vitepress": "2.0.0-alpha.16",
+    "vitepress-sidebar": "1.33.1"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264"
+}