docs(readme): refactor readme to explaining how to navigate this repository

CONTRIBUTING.md

@@ -6,6 +6,45 @@ On each PR that contains changes relevant to Docker builds, images are being bui
 
 > :evergreen_tree: Please be considerate when pushing commits and opening PR for multiple branches, as the process of building images uses energy and contributes to global warming.
 
+## Pull Request Process
+
+1. Test builds locally before submitting
+2. Follow conventional commit format
+3. Update documentation if needed
+4. Ensure all pre-commit checks pass
+5. Reference related issues in PR description
+
+## Commit Message Convention
+
+We recommend [Conventional Commits](https://www.conventionalcommits.org/) for clear and semantic commit history.
+
+Format: `<type>(<scope>): <description>`
+
+**Types:**
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, missing semicolons, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks (dependencies, build config, etc.)
+- `ci`: CI/CD changes
+
+**Examples:**
+
+```
+chore(deps): bump wkhtmltopdf version
+fix(ci): correct buildx cache configuration
+docs(contributing): add conventional commits guidelines
+```
+
+## Branch Naming
+
+- `feature/<description>` - New features
+- `fix/<description>` - Bug fixes
+- `docs/<description>` - Documentation updates
+
 ## Lint
 
 We use `pre-commit` framework to lint the codebase before committing.

README.md

@@ -1,25 +1,66 @@
+# Frappe Docker
+
 [![Build Stable](https://github.com/frappe/frappe_docker/actions/workflows/build_stable.yml/badge.svg)](https://github.com/frappe/frappe_docker/actions/workflows/build_stable.yml)
 [![Build Develop](https://github.com/frappe/frappe_docker/actions/workflows/build_develop.yml/badge.svg)](https://github.com/frappe/frappe_docker/actions/workflows/build_develop.yml)
 
-Everything about [Frappe](https://github.com/frappe/frappe) and [ERPNext](https://github.com/frappe/erpnext) in containers.
+Docker images and orchestration for Frappe applications.
 
-# Getting Started
+## What is this?
+
+This repository handles the containerization of the Frappe stack, including the application server, database, Redis, and supporting services. It provides quick disposable demo setups, a development environment, production-ready Docker images and compose configurations for deploying Frappe applications including ERPNext.
+
+## Repository Structure
+
+```
+frappe_docker/
+├── docs/                 # Complete documentation
+├── overrides/            # Docker Compose configurations for different scenarios
+├── compose.yaml          # Base Compose File for production setups
+├── pwd.yml               # Single Compose File for quick disposable demo
+├── images/               # Dockerfiles for building Frappe images
+├── development/          # Development environment configurations
+├── devcontainer-example/ # VS Code devcontainer setup
+└── resources/            # Helper scripts and configuration templates
+```
+
+> This section describes the structure of **this repository**, not the Frappe framework itself.
+
+### Key Components
+
+- `docs/` - Canonical documentation for all deployment and operational workflows
+- `overrides/` - Opinionated Compose overrides for common deployment patterns
+- `compose.yaml` - Base compose file for production setups (production)
+- `pwd.yml` - Disposable demo environment (non-production)
+
+## Documentation
+
+**The official documentation for `frappe_docker` is maintained in the `docs/` folder in this repository.**
 
 **New to Frappe Docker?** Read the [Getting Started Guide](docs/getting-started.md) for a comprehensive overview of repository structure, development workflow, custom apps, Docker concepts, and quick start examples.
 
-To get started you need [Docker](https://docs.docker.com/get-docker/), [docker-compose](https://docs.docker.com/compose/), and [git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git) setup on your machine. For Docker basics and best practices refer to Docker's [documentation](http://docs.docker.com).
+If you are already familiar with Frappe, you can jump right into the [different deployment methods](docs/01-getting-started/01-choosing-a-deployment-method.md) and select the one best suited to your use case.
 
-Once completed, chose one of the following two sections for next steps.
+## Prerequisites
 
-### Try in Play With Docker
+- [Docker](https://docs.docker.com/get-docker/)
+- [Docker Compose v2](https://docs.docker.com/compose/)
+- [git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git)
 
-To play in an already set up sandbox, in your browser, click the button below:
+> For Docker basics and best practices refer to Docker's [documentation](http://docs.docker.com)
+
+## Demo setup
+
+The fastest way to try Frappe is to play in an already set up sandbox, in your browser, click the button below:
 
 <a href="https://labs.play-with-docker.com/?stack=https://raw.githubusercontent.com/frappe/frappe_docker/main/pwd.yml">
   <img src="https://raw.githubusercontent.com/play-with-docker/stacks/master/assets/images/button.png" alt="Try in PWD"/>
 </a>
 
-### Try on your Dev environment
+### Try on your environment
+
+> **⚠️ Disposable demo only**
+>
+> **This setup is intended for quick evaluation. Expect to throw the environment away.** You will not be able to install custom apps to this setup. For production deployments, custom configurations, and detailed explanations, see the full documentation.
 
 First clone the repo:
 
@@ -28,28 +69,15 @@ git clone https://github.com/frappe/frappe_docker
 cd frappe_docker
 ```
 
-Then run: `docker compose -f pwd.yml up -d`
+Then run:
 
-### To run on ARM64 architecture follow this instructions
+```sh
+docker compose -f pwd.yml up -d
+```
 
-After you clone the repo and `cd frappe_docker`, run this command to build multi-architecture images specifically for ARM64.
+Wait for a couple of minutes for ERPNext site to be created or check `create-site` container logs before opening browser on port `8080`. (username: `Administrator`, password: `admin`)
 
-`docker buildx bake --no-cache --set "*.platform=linux/arm64"`
+## Documentation Links
-
-and then
-
-- add `platform: linux/arm64` to all services in the `pwd.yml`
-- replace the current specified versions of erpnext image on `pwd.yml` with `:latest`
-
-Then run: `docker compose -f pwd.yml up -d`
-
-## Final steps
-
-Wait for 5 minutes for ERPNext site to be created or check `create-site` container logs before opening browser on port 8080. (username: `Administrator`, password: `admin`)
-
-If you ran in a Dev Docker environment, to view container logs: `docker compose -f pwd.yml logs -f create-site`. Don't worry about some of the initial error messages, some services take a while to become ready, and then they go away.
-
-# Documentation
 
 ### [Getting Started Guide](docs/getting-started.md)
 
@@ -57,54 +85,26 @@ If you ran in a Dev Docker environment, to view container logs: `docker compose
 
 ### [Getting Started](#getting-started)
 
-- [Quick Start (Linux/Mac)](docs/01-getting-started/01-quick-start-linux-mac.md)
+### [Deployment Methods](docs/01-getting-started/01-choosing-a-deployment-method.md)
-- [Single Compose Setup](docs/01-getting-started/02-single-compose-setup.md)
 
-### [Setup](#setup)
+### [ARM64](docs/01-getting-started/03-arm64.md)
 
-- [Container Setup Overview](docs/02-setup/01-overview.md)
+### [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)
+### [Development](docs/05-development/01-development.md)
 
-- [TLS/SSL Setup](docs/03-production/01-tls-ssl-setup.md)
+## Contributing
-- [Backup Strategy](docs/03-production/02-backup-strategy.md)
-- [Multi-Tenancy](docs/03-production/03-multi-tenancy.md)
 
-### [Operations](#operations)
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-- [Site Operations](docs/04-operations/01-site-operations.md)
-
-### [Development](#development)
-
-- [Development Guide](docs/05-development/01-development.md)
-- [Debugging](docs/05-development/02-debugging.md)
-- [Local Services Connection](docs/05-development/03-local-services-connection.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
-
-If you want to contribute to this repo refer to [CONTRIBUTING.md](CONTRIBUTING.md)
 
 This repository is only for container related stuff. You also might want to contribute to:
 
-- [Frappe framework](https://github.com/frappe/frappe#contributing),
+## Resources
-- [ERPNext](https://github.com/frappe/erpnext#contributing),
+
+- [Frappe framework](https://github.com/frappe/frappe),
+- [ERPNext](https://github.com/frappe/erpnext),
 - [Frappe Bench](https://github.com/frappe/bench).
+
+## License
+
+This repository is licensed under the MIT License. See [LICENSE](LICENSE) for details.

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

@@ -1,18 +1,28 @@
 # How to install ERPNext on linux/mac using Frappe_docker ?
 
-step1: clone the repo
+## Clone the repo
 
-```
+```sh
 git clone https://github.com/frappe/frappe_docker
+cd frappe_docker
 ```
 
-step2: add platform: linux/amd64 to all services in the /pwd.yaml
+## buildx platform
 
-here is the update pwd.yml file
+Run this command to build multi-architecture images specifically for ARM64:
+
+```sh
+docker buildx bake --no-cache --set "*.platform=linux/arm64"
+```
+
+## add platform to all services
+
+- add platform: `linux/arm64` to all services in the `pwd.yml`
+- (replace the current specified versions of erpnext image on `pwd.yml` with `:latest`)
+
+here is the example pwd.yml file:
 
 ```yml
-version: "3"
-
 services:
   backend:
     image: frappe/erpnext:v15
@@ -209,14 +219,10 @@ volumes:
   logs:
 ```
 
-step3: run the docker
+## Run the compose file
 
-```
+```sh
-cd frappe_docker
+docker compose -f pwd.yml up
-```
-
-```
-docker-compose -f ./pwd.yml up
 ```
 
 ---