Frappe Docker

https://frappe.github.io/frappe_docker/
Admin
Frappe Docker provides a comprehensive containerized environment for developing and deploying Frappe...
Tokens:59,338
Snippets:541
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Quick Test: Docker Compose Setup

Source: https://frappe.github.io/frappe_docker/getting-started.html

Clone the repository, start the environment with `docker compose -f pwd.yml up -d`, monitor setup progress, and access the site at http://localhost:8080 with Administrator/admin. Cleanup with `docker compose -f pwd.yml down -v`.

```bash
# Clone and run
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
docker compose -f pwd.yml up -d

# Monitor setup progress (~5 minutes)
docker compose -f pwd.yml logs -f create-site

# When complete, access:
# URL: http://localhost:8080
# Username: Administrator
# Password: admin

# Cleanup when done
docker compose -f pwd.yml down -v

```

--------------------------------

### Create site with app installation

Source: https://frappe.github.io/frappe_docker/02-setup/03-start-setup.html

Creates a new site and installs the erpnext app in one command. Replace <sitename>, <db-password>, and <admin-password> with your values. Wait for the db service to start and configurator to exit before running this command.

```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
```

--------------------------------

### Quick test setup with pwd.yml

Source: https://frappe.github.io/frappe_docker/getting-started.html

Clone the repository and start the quick test environment using pwd.yml. Monitor site creation with logs and access the site at localhost:8080 with default credentials.

```bash
git clone https://github.com/frappe/frappe_docker
cd frappe_docker
docker compose -f pwd.yml up -d

# Monitor site creation (takes ~5 minutes)
docker compose -f pwd.yml logs -f create-site

# Access once "create-site" container exits successfully
# Visit http://localhost:8080
# Login: Administrator / admin
```

--------------------------------

### Example 3: Production Setup with HTTPS

Source: https://frappe.github.io/frappe_docker/02-setup/06-setup-examples.html

Generates and starts a production setup with containerized MariaDB and Redis, using Let's Encrypt SSL certificates via Traefik. Requires `LETSENCRYPT_EMAIL` and `SITES_RULE` environment variables, and 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
```

--------------------------------

### Copy the example environment file

Source: https://frappe.github.io/frappe_docker/02-setup/02-build-setup.html

Creates a custom environment file from the template. Edit custom.env to customize variables for your setup.

```bash
cp example.env custom.env
```

--------------------------------

### Create Multiple Frappe Sites in Development

Source: https://frappe.github.io/frappe_docker/getting-started.html

Quick example for multi-site hosting: create multiple sites in development using bench new-site. Each site gets its own database, with shared Redis and application code.

```bash
# See: docs/11-how-to/05-publish-multiple-sites-on-different-ports.md

# Quick example:
# 1. Create multiple sites in development
bench new-site site1.com
bench new-site site2.com

# 2. Configure Nginx/Traefik for routing
# 3. Each site gets own database
# 4. Shared Redis and application code
```

--------------------------------

### Navigate to docs directory

Source: https://frappe.github.io/frappe_docker/08-reference/02-configuring-vitepress.html

Change to the docs directory before installing dependencies and starting the development server.

```sh
cd docs
```

--------------------------------

### Create and Install a Custom App with bench

Source: https://frappe.github.io/frappe_docker/09-concepts/01-custom-app.html

Commands to create a new app, install it to a site, and create a DocType via the bench console. The console command shows an example of using bench.new_doc.

```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
```

--------------------------------

### Example 1: Frappe without Proxy (Direct Access)

Source: https://frappe.github.io/frappe_docker/02-setup/06-setup-examples.html

Generates and starts a Frappe setup with containerized MariaDB and Redis, exposing the application directly on port 8080 without a reverse proxy. Requires `DB_PASSWORD` in `.env` (or default `123`).

```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
```

--------------------------------

### Build assets and start the dev server

Source: https://frappe.github.io/frappe_docker/05-development/04-alternate-setup.html

Builds assets (optional) and starts the development server. After starting, open http://development.localhost:8000 and log in with Administrator / admin.

```bash
bench build # (optional)
bench start
```

--------------------------------

### Create new site with bench new-site (MariaDB)

Source: https://frappe.github.io/frappe_docker/04-operations/01-site-operations.html

Creates a new site using the default MariaDB database. Wait for the db service to start and configurator to exit (usually up to 10 seconds). Pass -p <project_name> if you used a custom project name. Use --install-app to install an app; see bench new-site --help for all options.

```sh
docker-compose exec backend bench new-site --mariadb-user-host-login-scope=% --db-root-password <db-password> --admin-password <admin-password> <site-name>
```

--------------------------------

### Start development server

Source: https://frappe.github.io/frappe_docker/getting-started.html

Start the Frappe development server with bench start. Access the site at http://localhost:8000 and edit files in the apps directory.

```bash
cd frappe-bench
bench start

# Access: http://localhost:8000
# Edit files in: development/frappe-bench/apps/
```

--------------------------------

### Install custom app with bench get-app and install-app

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Use --branch to point to a branch on a custom app repository, then install the app on the site development.localhost.

```shell
bench get-app --branch version-12 https://github.com/myusername/myapp
bench --site development.localhost install-app myapp
```

--------------------------------

### Example 2: ERPNext with External Database and Redis

Source: https://frappe.github.io/frappe_docker/02-setup/06-setup-examples.html

Generates and starts an ERPNext setup using external MariaDB and Redis instances with Traefik HTTP proxy. Requires `DB_HOST`, `DB_PORT`, `REDIS_CACHE`, and `REDIS_QUEUE` in `.env`.

```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
```

--------------------------------

### Install Frappe inside container

Source: https://frappe.github.io/frappe_docker/getting-started.html

Run the installer script inside the container to set up Frappe. Follow the prompts to specify the site name, install ERPNext, and choose the version.

```bash
cd /workspace/development
python installer.py

# Follow prompts:
# - Site name: development.localhost
# - Install ERPNext: Yes
# - Version: version-15
```

--------------------------------

### Production deployment overview

Source: https://frappe.github.io/frappe_docker/getting-started.html

Quick overview of production deployment. See the detailed guide at docs/single-server-example.md for full instructions.

```bash
# Follow detailed guide
# See: docs/single-server-example.md

# Quick overview:
```

--------------------------------

### Create a site with development.localhost

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Example of creating a site named development.localhost with the required option.

```shell
bench new-site --mariadb-user-host-login-scope=% development.localhost
```

--------------------------------

### Example pwd.yml with platform linux/arm64

Source: https://frappe.github.io/frappe_docker/01-getting-started/03-arm64.html

Example pwd.yml file with platform: linux/arm64 added to all services and erpnext image version replaced with :latest.

```yml
services:
  backend:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  configurator:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: none
    entrypoint:
      - bash
      - -c
    # add redis_socketio for backward compatibility
    command:
      - >
        ls -1 apps > sites/apps.txt;
        bench set-config -g db_host $$DB_HOST;
        bench set-config -gp db_port $$DB_PORT;
        bench set-config -g redis_cache "redis://$$REDIS_CACHE";
        bench set-config -g redis_queue "redis://$$REDIS_QUEUE";
        bench set-config -g redis_socketio "redis://$$REDIS_QUEUE";
        bench set-config -gp socketio_port $$SOCKETIO_PORT;
    environment:
      DB_HOST: db
      DB_PORT: "3306"
      REDIS_CACHE: redis-cache:6379
      REDIS_QUEUE: redis-queue:6379
      SOCKETIO_PORT: "9000"
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  create-site:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: none
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    entrypoint:
      - bash
      - -c
    command:
      - >
        wait-for-it -t 120 db:3306;
        wait-for-it -t 120 redis-cache:6379;
        wait-for-it -t 120 redis-queue:6379;
        export start=`date +%s`;
        until [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".db_host // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_cache // empty"` ]] && \
          [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_queue // empty"` ]];
        do
          echo "Waiting for sites/common_site_config.json to be created";
          sleep 5;
          if (( `date +%s`-start > 120 )); then
            echo "could not find sites/common_site_config.json with required keys";
            exit 1
          fi
        done;
        echo "sites/common_site_config.json found";
        bench new-site --mariadb-user-host-login-scope=% --admin-password=admin --db-root-password=admin --install-app erpnext --set-default frontend;

  db:
    image: mariadb:11.8
    platform: linux/arm64
    healthcheck:
      test: mysqladmin ping -h localhost --password=admin
      interval: 1s
      retries: 20
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
      - --skip-character-set-client-handshake
    environment:
      MYSQL_ROOT_PASSWORD: admin
    volumes:
      - db-data:/var/lib/mysql

  frontend:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    depends_on:
      - websocket
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - nginx-entrypoint.sh
    environment:
      BACKEND: backend:8000
      FRAPPE_SITE_NAME_HEADER: frontend
      SOCKETIO: websocket:9000
      UPSTREAM_REAL_IP_ADDRESS: 127.0.0.1
      UPSTREAM_REAL_IP_HEADER: X-Forwarded-For
      UPSTREAM_REAL_IP_RECURSIVE: "off"
      PROXY_READ_TIMEOUT: 120
      CLIENT_MAX_BODY_SIZE: 50m
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs
    ports:
      - "8080:8080"

  queue-long:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - long,default,short
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  queue-short:
    image: frappe/erpnext:v16.19.1
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: on-failure
    command:
      - bench
      - worker
      - --queue
      - short,default
    volumes:
      - sites:/home/frappe/frappe-bench/sites
      - logs:/home/frappe/frappe-bench/logs

  redis-queue:
    image: redis:6.2-alpine
    platform: linux/arm64
    deploy:
      restart_policy:
        condition: on-failure
    volumes:
      - redis-queue-data:/data
```

--------------------------------

### Start the stack

Source: https://frappe.github.io/frappe_docker/02-setup/08-single-server-nginxproxy-example.html

Starts the stack with the rendered compose file. Includes MariaDB and Redis containers.

```shell
docker compose --project-name erpnext -f ~/gitops/erpnext.yaml up -d
```

--------------------------------

### Install Docker using convenience script

Source: https://frappe.github.io/frappe_docker/02-setup/07-single-server-example.html

Installs Docker on a Linux server using the official convenience script. Assumes Ubuntu LTS server, but any distribution where the script works is acceptable.

```shell
curl -fsSL https://get.docker.com | bash
```

--------------------------------

### Start Frappe bench without debugging

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Run this command from the frappe-bench directory to start the bench. Login with user 'Administrator' and the password you chose when creating the site. The website will be accessible at development.localhost:8000.

```shell
bench start
```

--------------------------------

### Copy example.env to .env

Source: https://frappe.github.io/frappe_docker/02-setup/06-setup-examples.html

Copies the example environment file to `.env` for editing. This is the first step in setting up environment variables.

```sh
cp example.env .env
```

--------------------------------

### Initial fork setup

Source: https://frappe.github.io/frappe_docker/getting-started.html

Steps to fork the frappe_docker repository on GitHub, clone your fork, and add the original repository as an upstream remote.

```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
```

--------------------------------

### Run automated installer

Source: https://frappe.github.io/frappe_docker/getting-started.html

Run the installer script inside the development container to set up the Frappe environment. Follow interactive prompts for site name and apps.

```bash
cd /workspace/development
python installer.py
# Follow interactive prompts for site name, apps to install, etc.
```

--------------------------------

### Start VitePress development server

Source: https://frappe.github.io/frappe_docker/08-reference/02-configuring-vitepress.html

Start the VitePress development server. The preview is available at http://localhost:5173/frappe_docker and updates as you make changes.

```sh
pnpm run docs:dev
```

--------------------------------

### Show installer.py help

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Displays usage and options for installer.py. Shows defaults for apps-json, bench-name, site-name, frappe-repo, frappe-branch, admin-password, and db-type.

```shell
python installer.py --help
usage: installer.py [-h] [-j APPS_JSON] [-b BENCH_NAME] [-s SITE_NAME] [-r FRAPPE_REPO] [-t FRAPPE_BRANCH] [-p PY_VERSION] [-n NODE_VERSION] [-v] [-a ADMIN_PASSWORD] [-d DB_TYPE]

options:
  -h, --help            show this help message and exit
  -j APPS_JSON, --apps-json APPS_JSON
                        Path to apps.json, default: apps-example.json
  -b BENCH_NAME, --bench-name BENCH_NAME
                        Bench directory name, default: frappe-bench
  -s SITE_NAME, --site-name SITE_NAME
                        Site name, should end with .localhost, default: development.localhost
  -r FRAPPE_REPO, --frappe-repo FRAPPE_REPO
                        frappe repo to use, default: https://github.com/frappe/frappe
  -t FRAPPE_BRANCH, --frappe-branch FRAPPE_BRANCH
                        frappe repo to use, default: version-15
  -p PY_VERSION, --py-version PY_VERSION
                        python version, default: Not Set
  -n NODE_VERSION, --node-version NODE_VERSION
                        node version, default: Not Set
  -v, --verbose         verbose output
  -a ADMIN_PASSWORD, --admin-password ADMIN_PASSWORD
                        admin password for site, default: admin
  -d DB_TYPE, --db-type DB_TYPE
                        Database type to use (e.g., mariadb or postgres)
```

--------------------------------

### Create site two.example.com on first bench

Source: https://frappe.github.io/frappe_docker/02-setup/07-single-server-example.html

Command to create a new site on the first bench (erpnext-one) using the bench CLI. It sets the database root password to 'changeit' and installs the ERPNext app.

```shell
docker compose --project-name erpnext-one exec backend \
  bench new-site --mariadb-user-host-login-scope=% --db-root-password changeit --install-app erpnext --admin-password changeit two.example.com
```

--------------------------------

### Basic site creation with Podman

Source: https://frappe.github.io/frappe_docker/02-setup/03-start-setup.html

Creates a new site and installs the erpnext app inside the backend container. Replace <sitename> with your desired site name.

```bash
podman exec -ti erpnext_backend_1 /bin/bash
bench new-site <sitename> --mariadb-user-host-login-scope='172.%.%.%'
bench --site <sitename> install-app erpnext
```

--------------------------------

### Compose setup with nginx-proxy and acme-companion overrides

Source: https://frappe.github.io/frappe_docker/11-how-to/02-nginx-proxy-acme-companion.html

Generate a combined docker-compose.yml using both nginx-proxy overrides, then start the stack. Replace database and Redis overrides if using external services.

```sh
docker compose -f compose.yaml \
  -f overrides/compose.mariadb.yaml \
  -f overrides/compose.redis.yaml \
  -f overrides/compose.nginxproxy.yaml \
  -f overrides/compose.nginxproxy-ssl.yaml \
  config > ~/gitops/docker-compose.yml

docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
```

--------------------------------

### Configure environment file for bench

Source: https://frappe.github.io/frappe_docker/02-setup/08-single-server-nginxproxy-example.html

Copies example.env, sets DB password, and adds NGINX_PROXY_HOSTS and LETSENCRYPT_EMAIL. Replace placeholders with production values.

```shell
cp example.env ~/gitops/erpnext.env
sed -i 's/DB_PASSWORD=123/DB_PASSWORD=changeit/g' ~/gitops/erpnext.env
echo 'NGINX_PROXY_HOSTS=erp.your-domain.com,crm.your-domain.com' >> ~/gitops/erpnext.env
echo 'LETSENCRYPT_EMAIL=admin@your-domain.com' >> ~/gitops/erpnext.env
```

--------------------------------

### Start Frappe with VSCode Python debugging

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Run this command instead of 'bench start' to start bench processes for debugging. Starts socketio, watch, schedule, worker_short, and worker_long. Redis and web process are excluded; web can be started from VSCode debugger.

```shell
honcho start \
    socketio \
    watch \
    schedule \
    worker_short \
    worker_long
```

--------------------------------

### Create erpnext-two.env environment file

Source: https://frappe.github.io/frappe_docker/02-setup/07-single-server-example.html

Downloads the example environment file and modifies it for the second bench. Sets the database password, host, port, router, sites rule, and bench network. The password should be changed from 'changeit' to the one used for MariaDB.

```shell
curl -sL https://raw.githubusercontent.com/frappe/frappe_docker/main/example.env -o ~/gitops/erpnext-two.env
sed -i 's/DB_PASSWORD=123/DB_PASSWORD=changeit/g' ~/gitops/erpnext-two.env
sed -i 's/DB_HOST=/DB_HOST=mariadb-database/g' ~/gitops/erpnext-two.env
sed -i 's/DB_PORT=/DB_PORT=3306/g' ~/gitops/erpnext-two.env
echo "ROUTER=erpnext-two" >> ~/gitops/erpnext-two.env
echo 'SITES_RULE=Host(`three.example.com`) || Host(`four.example.com`)' >> ~/gitops/erpnext-two.env
echo "BENCH_NETWORK=erpnext-two" >> ~/gitops/erpnext-two.env
```

--------------------------------

### Install ERPNext version-13

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Installs ERPNext from the version-13 branch.

```shell
bench get-app --branch version-13 erpnext
bench --site development.localhost install-app erpnext
```

--------------------------------

### Install ERPNext version-14 with --resolve-deps

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Installs ERPNext from the version-14 branch. The --resolve-deps flag is used because the Payments app has been factored out and ERPNext will not install it automatically.

```shell
bench get-app --branch version-14 --resolve-deps erpnext
bench --site development.localhost install-app erpnext
```

--------------------------------

### Install Dev Containers extension via command line

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Installs the VSCode Dev Containers extension using the command line. Alternative to manual installation from the marketplace.

```shell
code --install-extension ms-vscode-remote.remote-containers
```

--------------------------------

### Create site one.example.com on erpnext-one bench

Source: https://frappe.github.io/frappe_docker/02-setup/07-single-server-example.html

Creates a new site one.example.com on the erpnext-one bench with the specified database root password and admin password. This is the first site creation command.

```shell
# one.example.com
docker compose --project-name erpnext-one exec backend \
  bench new-site --mariadb-user-host-login-scope=% --db-root-password changeit --install-app erpnext --admin-password changeit one.example.com
```

--------------------------------

### Copy example devcontainer config

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Copies the example devcontainer configuration from `devcontainer-example` to `.devcontainer`.

```shell
cp -R devcontainer-example .devcontainer
```

--------------------------------

### Install dependencies with pnpm

Source: https://frappe.github.io/frappe_docker/08-reference/02-configuring-vitepress.html

Install the project dependencies using pnpm. Requires pnpm v10.28 or above.

```sh
pnpm install
```

--------------------------------

### Run installer.py to create bench/site

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Automates creating a new bench/site and installing apps. Default admin password is 'admin'. Pass --db-type postgres for PostgreSQL. Uses apps-example.json by default.

```shell
python installer.py  #pass --db-type postgres for postgresdb
```

--------------------------------

### Start containers with docker compose

Source: https://frappe.github.io/frappe_docker/05-development/04-alternate-setup.html

Starts the development containers in detached mode using the compose file in .devcontainer.

```bash
docker compose -f .devcontainer/docker-compose.yml up -d
```

--------------------------------

### Start development containers with docker-compose

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Starts the development containers defined in the .devcontainer/docker-compose.yml file. Used when not using VS Code.

```shell
docker-compose -f .devcontainer/docker-compose.yml up -d
```

--------------------------------

### Start the stack with regenerated compose config

Source: https://frappe.github.io/frappe_docker/06-migration/02-traefik-v3-migration.html

Command to start the stack using the regenerated compose file. Replace <project-name> with your project name.

```sh
docker compose --project-name <project-name> -f ~/gitops/docker-compose.yml up -d
```

--------------------------------

### Start containers with Podman

Source: https://frappe.github.io/frappe_docker/02-setup/03-start-setup.html

Starts all containers using podman-compose with the project name 'frappe'. The --in-pod=1 flag runs containers in a pod.

```bash
podman-compose --in-pod=1 --project-name frappe -f compose.custom.yaml up -d
```

--------------------------------

### Enter development container and create app

Source: https://frappe.github.io/frappe_docker/getting-started.html

Commands to enter the running container, create a new app, install it to a site, and create a DocType via console. The bench new-app command prompts interactively for details.

```bash
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
```

--------------------------------

### Copy example vscode config for devcontainer

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Copies the example VSCode configuration for the devcontainer from `development/vscode-example` to `development/.vscode`. This sets up basic configuration for debugging.

```shell
cp -R development/vscode-example development/.vscode
```

--------------------------------

### Start containers with Docker Compose

Source: https://frappe.github.io/frappe_docker/02-setup/03-start-setup.html

Starts all containers defined in compose.custom.yaml with the project name 'frappe'. The -p flag names the project for easy management.

```bash
docker compose -p frappe -f compose.custom.yaml up -d
```

--------------------------------

### Basic site creation with Docker Compose

Source: https://frappe.github.io/frappe_docker/02-setup/03-start-setup.html

Creates a new site and installs the erpnext app. Replace <sitename> with your desired site name. The --mariadb-user-host-login-scope flag allows connections from any IP in the 172.0.0.0/8 range.

```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
```

--------------------------------

### Update Image and Start Containers with docker compose up -d

Source: https://frappe.github.io/frappe_docker/06-migration/03-postgres-major-version-upgrade.html

Starts the containers with the updated PostgreSQL 15 image after updating overrides/compose.postgres.yaml or pulling the latest changes.

```bash
docker compose up -d
```

--------------------------------

### Initial Fork Setup

Source: https://frappe.github.io/frappe_docker/08-reference/03-fork-management.html

Commands to fork the repository on GitHub, clone your fork, add the upstream remote, verify remotes, and create a development branch.

```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
```

--------------------------------

### Create-site service configuration for single image

Source: https://frappe.github.io/frappe_docker/06-migration/01-migrate-from-multi-image-setup.html

For the create-site service to act as run once site creation job, pass ["bash", "-c"] as container entrypoint and bash script inline to yaml. Use --mariadb-user-host-login-scope=% as upstream bench is installed in container. The WORKDIR has changed to /home/frappe/frappe-bench, so the path to common_site_config.json is sites/common_site_config.json.

```yaml
# ... removed for brevity
create-site:
  image: frappe/erpnext:${ERPNEXT_VERSION:?ERPNext version not set}
  restart: "no"
  entrypoint:
    - bash
    - -c
  command:
    - >
      wait-for-it -t 120 db:3306;
      wait-for-it -t 120 redis-cache:6379;
      wait-for-it -t 120 redis-queue:6379;
      export start=`date +%s`;
      until [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".db_host // empty"` ]] && \
        [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_cache // empty"` ]] && \
        [[ -n `grep -hs ^ sites/common_site_config.json | jq -r ".redis_queue // empty"` ]];
      do
        echo "Waiting for sites/common_site_config.json to be created";
        sleep 5;
        if (( `date +%s`-start > 120 )); then
          echo "could not find sites/common_site_config.json with required keys";
          exit 1
        fi
      done;
      echo "sites/common_site_config.json found";
      bench new-site --mariadb-user-host-login-scope=% --admin-password=admin --db-root-password=admin --install-app erpnext --set-default frontend;

# ... removed for brevity
```

--------------------------------

### Create a new site with bench

Source: https://frappe.github.io/frappe_docker/05-development/01-development.html

Creates a new Frappe site with the --mariadb-user-host-login-scope=% option for Docker compatibility. The sitename must end with .localhost.

```shell
bench new-site --mariadb-user-host-login-scope=% sitename
```

--------------------------------

### Install Docker Compose V2

Source: https://frappe.github.io/frappe_docker/02-setup/07-single-server-example.html

Installs Docker Compose v2.2.3 as a CLI plugin. Downloads the binary to the Docker CLI plugins directory and makes it executable.

```shell
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.2.3/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
```
Tokens:
Raw