From aafc25bc76339ea84e89c821d28fac458dc41c9c Mon Sep 17 00:00:00 2001 From: Harshith Ashok Date: Sun, 17 May 2026 07:45:04 +0530 Subject: [PATCH 1/5] docs(contributing): add docker dev guide --- README.md | 1 + docs/10-development/01-setup.md | 252 ++++++++++++++++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 docs/10-development/01-setup.md diff --git a/README.md b/README.md index 769efef7..ac8479a4 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,7 @@ The full `frappe_docker` documentation is available in [`docs/`](docs/) and publ - **Running in production:** [Production docs](docs/03-production/) - **Operating a deployment:** [Operations docs](docs/04-operations/) - **Development workflows:** [Development](docs/05-development/01-development.md) +- **Docker Container Setup for Development** [Docker Setup](docs/10-development/01-setup.md) - **FAQ:** [Frequently Asked Questions](https://github.com/frappe/frappe_docker/wiki/Frequently-Asked-Questions) ## Prerequisites diff --git a/docs/10-development/01-setup.md b/docs/10-development/01-setup.md new file mode 100644 index 00000000..3577acb3 --- /dev/null +++ b/docs/10-development/01-setup.md @@ -0,0 +1,252 @@ +--- +title: Docker Development Setup +--- + +# Docker Development Setup + +A complete guide for setting up a Frappe development environment on x86 and ARM based computers running UNIX based OSes by running containers directly and working inside them via the terminal. No VS Code Dev Containers extension needed. + +--- + +## Prerequisites + +- **Docker Desktop** (Applicable only for MacOS) — [download here](https://www.docker.com/products/docker-desktop/) +- **Git** +- A terminal (iTerm2, or the built-in Terminal.app) + +### Docker Desktop Resource Allocation (Critical) + +1. Open Docker Desktop → **Settings** → **Resources** +2. **Memory**: at least **6 GB** (8 GB recommended) +3. **CPUs**: at least **4** +4. **Disk image size**: at least **60 GB** +5. Click **Apply & Restart** + +--- + +## Step 1 — Set ARM64 as Default Platform (ONLY FOR ARM BASED SYSTEMS) + +```bash +export DOCKER_DEFAULT_PLATFORM=linux/arm64 +``` + +Make it permanent: + +```bash +echo 'export DOCKER_DEFAULT_PLATFORM=linux/arm64' >> ~/.zshrc +source ~/.zshrc +``` + +--- + +## Step 2 — Clone the Repo + +```bash +git clone https://github.com/frappe/frappe_docker.git +cd frappe_docker +``` + +--- + +## Step 3 — Set Up the Dev Container Config + +The `devcontainer-example/` folder contains a ready-made `docker-compose.yml` for development. Copy it into place: + +```bash +cp -R devcontainer-example .devcontainer +``` + +This gives you `.devcontainer/docker-compose.yml` which defines all the services you need: + +- `frappe` — the main development container (Debian, Python, Node, bench) +- `mariadb` — the database +- `redis-cache` — cache layer +- `redis-queue` — background job queue + +--- + +## Step 4 — Add ARM64 Platform to All Services + +Open `.devcontainer/docker-compose.yml` in any editor and add `platform: linux/arm64` to every service block. It should look like this: + +```yaml +services: + frappe: + image: frappe/bench:latest + platform: linux/arm64 + # ... rest of config + + mariadb: + image: mariadb:10.8 + platform: linux/arm64 + # ... + + redis-cache: + image: redis:6.2-alpine + platform: linux/arm64 + # ... + + redis-queue: + image: redis:6.2-alpine + platform: linux/arm64 + # ... +``` + +> Without this, Docker may pull amd64 images and emulate them via Rosetta — things will work but be noticeably slower. +> Ensure mariadb version is set to `10.8` since Frappe Framework is not yet tested for the default version `11.8` + +--- + +## Step 5 — Start the Containers + +```bash +docker compose -f .devcontainer/docker-compose.yml up -d +``` + +Verify everything is running: + +```bash +docker compose -f .devcontainer/docker-compose.yml ps +``` + +You should see all services with status `Up`. + +In case you get any errors along the lines of, + +```log +Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint devcontainer-frappe-1 (44b337b68d100e914fab0ce446ed08d791cc73aaffb05cf47c347c00ff88f567): Bind for 0.0.0.0:9001 failed: port is already allocated +``` + +- Check if the port is being used by another service with `lsof -i :PORT` + > Usually on MacOS ports 8000 and 9000 are usually reserved for system use +- Go to line 60 and 61 under the `frappe` service and change the ports + +Eg: + +``` +ports: + - 8001-8005:8001-8005 + - 9002-9005:9002-9005 +``` + +--- + +## Step 6 — Enter the Development Container + +```bash +docker exec -e "TERM=xterm-256color" -w /workspace/development -it devcontainer-frappe-1 bash +``` + +> The container name is typically `devcontainer-frappe-1`. If it differs, check with `docker ps` and use the actual name shown. + +You are now inside the container as the `frappe` user. All subsequent commands in this guide run **inside the container** unless noted otherwise. + +--- + +## Step 7 — Initialize a Bench + +```bash +bench init --skip-redis-config-generation --frappe-branch version-16 frappe-bench +cd frappe-bench +``` + +Use `version-16` for the latest stable release. Swap for `version-15` if needed. + +This creates: + +``` +development/ +└── frappe-bench/ + ├── apps/ ← All Frappe apps live here + ├── sites/ ← Your sites (databases, uploaded files) + ├── env/ ← Python virtualenv + ├── logs/ + └── Procfile +``` + +--- + +## Step 8 — Configure Service Hosts + +Tell bench to use the containerised services (not localhost): + +```bash +bench set-config -g db_host mariadb +bench set-config -g redis_cache redis://redis-cache:6379 +bench set-config -g redis_queue redis://redis-queue:6379 +bench set-config -g redis_socketio redis://redis-queue:6379 +``` + +If any command fails, edit the file directly: + +```bash +nano sites/common_site_config.json +``` + +Paste: + +```json +{ + "db_host": "mariadb", + "redis_cache": "redis://redis-cache:6379", + "redis_queue": "redis://redis-queue:6379", + "redis_socketio": "redis://redis-queue:6379" +} +``` + +--- + +## Step 9 — Fix the Procfile + +Redis runs in separate containers, so remove it from Honcho's Procfile to avoid conflicts: + +```bash +sudo sed -i '/redis/d' ./Procfile +``` + +--- + +## Step 10 — Create a Site + +```bash +bench new-site \ + --db-root-password 123 \ + --admin-password admin \ + --mariadb-user-host-login-scope=% \ + development.localhost +``` + +- MariaDB root password: `123` (set in the docker-compose defaults) +- Admin password: `admin` (change this to whatever you want) +- Site name **must end in `.localhost`** + +--- + +## Step 11 — Enable Developer Mode + +```bash +bench --site development.localhost set-config developer_mode 1 +bench --site development.localhost clear-cache +``` + +--- + +## Step 12 — Add development.localhost to /etc/hosts (on your Mac) + +Run this **on your Mac** (not inside the container): + +```bash +echo "127.0.0.1 development.localhost" | sudo tee -a /etc/hosts +``` + +--- + +## Step 13 — Start the Dev Server + +```bash +bench build # (optional) +bench start +``` + +Open your browser at **http://development.localhost:8000** +Login: `Administrator` / `admin` From cfd280eff3aac9cc2403e2baab0d117f4575de92 Mon Sep 17 00:00:00 2001 From: Harshith Ashok <50227707+harshith-ashok@users.noreply.github.com> Date: Sun, 17 May 2026 09:21:54 +0530 Subject: [PATCH 2/5] Clarify mariadb version requirement in setup Add note about mariadb version for Frappe Framework. --- docs/10-development/01-setup.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/10-development/01-setup.md b/docs/10-development/01-setup.md index 3577acb3..485e7387 100644 --- a/docs/10-development/01-setup.md +++ b/docs/10-development/01-setup.md @@ -93,8 +93,7 @@ services: ``` > Without this, Docker may pull amd64 images and emulate them via Rosetta — things will work but be noticeably slower. -> Ensure mariadb version is set to `10.8` since Frappe Framework is not yet tested for the default version `11.8` - +> --- ## Step 5 — Start the Containers From 5097115d08db19511c829beeb47517022dd72546 Mon Sep 17 00:00:00 2001 From: Harshith Ashok <50227707+harshith-ashok@users.noreply.github.com> Date: Sun, 17 May 2026 09:26:23 +0530 Subject: [PATCH 3/5] Update setup.md with mariadb version change advice Added note about mariadb version causing errors. This addition is based on Issue #1908 which I too faced while testing and setting it up myself. --- docs/10-development/01-setup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/10-development/01-setup.md b/docs/10-development/01-setup.md index 485e7387..567cb558 100644 --- a/docs/10-development/01-setup.md +++ b/docs/10-development/01-setup.md @@ -93,7 +93,8 @@ services: ``` > Without this, Docker may pull amd64 images and emulate them via Rosetta — things will work but be noticeably slower. -> +> Few users did note that the version of mariadb causes an error while creating a new site so in case you do encouter it change the version from `11.8` to `10.8` + --- ## Step 5 — Start the Containers From 6e1117bbbc2cdc900df4a855321f67e96bd712cb Mon Sep 17 00:00:00 2001 From: Harshith Ashok Date: Tue, 19 May 2026 00:22:22 +0530 Subject: [PATCH 4/5] removed old file and replaced it under development --- README.md | 1 - .../01-setup.md => 05-development/04-alternate-setup.md} | 5 ++++- 2 files changed, 4 insertions(+), 2 deletions(-) rename docs/{10-development/01-setup.md => 05-development/04-alternate-setup.md} (95%) diff --git a/README.md b/README.md index ac8479a4..769efef7 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,6 @@ The full `frappe_docker` documentation is available in [`docs/`](docs/) and publ - **Running in production:** [Production docs](docs/03-production/) - **Operating a deployment:** [Operations docs](docs/04-operations/) - **Development workflows:** [Development](docs/05-development/01-development.md) -- **Docker Container Setup for Development** [Docker Setup](docs/10-development/01-setup.md) - **FAQ:** [Frequently Asked Questions](https://github.com/frappe/frappe_docker/wiki/Frequently-Asked-Questions) ## Prerequisites diff --git a/docs/10-development/01-setup.md b/docs/05-development/04-alternate-setup.md similarity index 95% rename from docs/10-development/01-setup.md rename to docs/05-development/04-alternate-setup.md index 567cb558..29de8669 100644 --- a/docs/10-development/01-setup.md +++ b/docs/05-development/04-alternate-setup.md @@ -6,6 +6,9 @@ title: Docker Development Setup A complete guide for setting up a Frappe development environment on x86 and ARM based computers running UNIX based OSes by running containers directly and working inside them via the terminal. No VS Code Dev Containers extension needed. +> [!IMPORTANT] +> Devcontainers are the intended development setup for Frappe Framework but in case you don't want to use that method follow these instructions to use the CLI directly instead + --- ## Prerequisites @@ -93,7 +96,7 @@ services: ``` > Without this, Docker may pull amd64 images and emulate them via Rosetta — things will work but be noticeably slower. -> Few users did note that the version of mariadb causes an error while creating a new site so in case you do encouter it change the version from `11.8` to `10.8` +> Ensure mariadb version is set to `10.8` since Frappe Framework is not yet tested for the default version `11.8` --- From 48764b21c18ede53c311ea1ec60a3ff4783466dc Mon Sep 17 00:00:00 2001 From: Harshith Ashok <50227707+harshith-ashok@users.noreply.github.com> Date: Tue, 19 May 2026 19:55:03 +0530 Subject: [PATCH 5/5] remove mariadb version for Frappe Framework setup --- docs/05-development/04-alternate-setup.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/05-development/04-alternate-setup.md b/docs/05-development/04-alternate-setup.md index 29de8669..d2027479 100644 --- a/docs/05-development/04-alternate-setup.md +++ b/docs/05-development/04-alternate-setup.md @@ -96,7 +96,6 @@ services: ``` > Without this, Docker may pull amd64 images and emulate them via Rosetta — things will work but be noticeably slower. -> Ensure mariadb version is set to `10.8` since Frappe Framework is not yet tested for the default version `11.8` ---