From 12e6e821bcf22b8bdb8a896fec154901d89fdb1b Mon Sep 17 00:00:00 2001 From: jslocomotor <210083531+jslocomotor@users.noreply.github.com> Date: Wed, 29 Apr 2026 18:57:49 +0200 Subject: [PATCH 1/4] feat(compose): add migrator service override and documentation --- docs/02-setup/05-overrides.md | 6 ++- .../06-automated-builds-and-deployment.md | 19 ++++++++ overrides/compose.migrator.yaml | 45 +++++++++++++++++++ 3 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 overrides/compose.migrator.yaml diff --git a/docs/02-setup/05-overrides.md b/docs/02-setup/05-overrides.md index c81bf153..f10c6045 100644 --- a/docs/02-setup/05-overrides.md +++ b/docs/02-setup/05-overrides.md @@ -24,8 +24,10 @@ docker compose -f compose.yaml -f overrides/compose.mariadb.yaml -f overrides/co | compose.nginxproxy.yaml | Uses nginx-proxy as HTTP reverse proxy on port `:80` | Set `NGINX_PROXY_HOSTS`. Use with `compose.nginxproxy-ssl.yaml` for HTTPS. You can change the published port by setting `HTTP_PUBLISH_PORT` | | compose.nginxproxy-ssl.yaml | Adds acme-companion for HTTPS on port `:443` with automatic certificates | Requires `compose.nginxproxy.yaml`. Set `NGINX_PROXY_HOSTS` and `LETSENCRYPT_EMAIL`. `HTTP_PUBLISH_PORT` and `HTTPS_PUBLISH_PORT` can be set. | | **Redis** | | | -| compose.redis.yaml | Adds Redis service for caching and background job queuing | -| **TBD** | **The following overrides are available but lack documentation. If you use them and understand their purpose, please consider contributing to this documentation.** | +| compose.redis.yaml | Adds Redis service for caching and background job queuing | | +| **Services** | | | +| compose.migrator.yaml | Runs a dedicated migration container performing `bench migrate` on a site at every start | Set `SITE_NAME` | +| **TBD** | **The following overrides are available but lack documentation. If you use them and understand their purpose, please consider contributing to this documentation.** | | | compose.backup-cron.yaml | | | | compose.custom-domain-ssl.yaml | | | | compose.custom-domain.yaml | | | diff --git a/docs/03-production/06-automated-builds-and-deployment.md b/docs/03-production/06-automated-builds-and-deployment.md index 85113f51..1b71613b 100644 --- a/docs/03-production/06-automated-builds-and-deployment.md +++ b/docs/03-production/06-automated-builds-and-deployment.md @@ -126,3 +126,22 @@ Note: When using branch references in `apps.json`, the hash only changes when th --tag=custom:16 \ --file=images/layered/Containerfile . ``` + +## Automated deployment + +### Automate site migration + +After updating a custom image or deploying new app versions, a database migration +must be executed using `bench migrate`. + +Without running migrations, the site may become inconsistent or fail to start properly. + +For automated deployments, this step should not be performed manually. + +Consider using the dedicated `migrator` service provided as a Compose override. +It ensures that migrations are executed automatically when the stack starts. + +This approach is especially useful in CI/CD pipelines where no interactive access +to the backend container is available. + +See [Compose override](../../overrides/compose.migrator.yaml) diff --git a/overrides/compose.migrator.yaml b/overrides/compose.migrator.yaml new file mode 100644 index 00000000..aebc30a8 --- /dev/null +++ b/overrides/compose.migrator.yaml @@ -0,0 +1,45 @@ +# Provides a service for automated migration of a given site. +# Add SITE_NAME to .env + +# Compose extension fields of base compose.yaml. See https://github.com/frappe/frappe_docker/blob/main/compose.yaml +# Needed for merging compose files. +x-customizable-image: &customizable_image + # By default the image used only contains the `frappe` and `erpnext` apps. + # See https://github.com/frappe/frappe_docker/blob/main/docs/02-setup/02-build-setup.md#define-custom-apps + # about using custom images. + image: ${CUSTOM_IMAGE:-frappe/erpnext}:${CUSTOM_TAG:-$ERPNEXT_VERSION} + pull_policy: ${PULL_POLICY:-always} + restart: ${RESTART_POLICY:-unless-stopped} + +x-depends-on-configurator: &depends_on_configurator + depends_on: + configurator: + condition: service_completed_successfully + +x-backend-defaults: &backend_defaults + <<: [*depends_on_configurator, *customizable_image] + volumes: + - sites:/home/frappe/frappe-bench/sites + +services: + migrator: + <<: *backend_defaults + platform: linux/amd64 + entrypoint: + - bash + - -c + command: + - > + if [ -z "$$SITE_NAME" ]; then + echo "[migrator] SITE_NAME is not set"; + exit 1; + fi; + if [ -d "sites/$$SITE_NAME" ]; then + echo "[migrator] Migrating $$SITE_NAME"; + bench --site $$SITE_NAME migrate; + else + echo "[migrator] Site $$SITE_NAME not found, skipping migrate"; + fi + environment: + SITE_NAME: ${SITE_NAME} + restart: on-failure From ae221ebf7ab6b7db467a7c9242801188cb1673f4 Mon Sep 17 00:00:00 2001 From: jslocomotor <210083531+jslocomotor@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:15:58 +0200 Subject: [PATCH 2/4] feat(migrator): add multi-site support to migration --- docs/02-setup/05-overrides.md | 2 +- overrides/compose.migrator.yaml | 23 +++++++++++------------ 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/02-setup/05-overrides.md b/docs/02-setup/05-overrides.md index f10c6045..ee3f64af 100644 --- a/docs/02-setup/05-overrides.md +++ b/docs/02-setup/05-overrides.md @@ -26,7 +26,7 @@ docker compose -f compose.yaml -f overrides/compose.mariadb.yaml -f overrides/co | **Redis** | | | | compose.redis.yaml | Adds Redis service for caching and background job queuing | | | **Services** | | | -| compose.migrator.yaml | Runs a dedicated migration container performing `bench migrate` on a site at every start | Set `SITE_NAME` | +| compose.migrator.yaml | Runs a dedicated migration container performing `bench --site all migrate` on a site at every start | Control via `MIGRATE_SITES` - defaults to true | | **TBD** | **The following overrides are available but lack documentation. If you use them and understand their purpose, please consider contributing to this documentation.** | | | compose.backup-cron.yaml | | | | compose.custom-domain-ssl.yaml | | | diff --git a/overrides/compose.migrator.yaml b/overrides/compose.migrator.yaml index aebc30a8..8a96107f 100644 --- a/overrides/compose.migrator.yaml +++ b/overrides/compose.migrator.yaml @@ -1,5 +1,4 @@ # Provides a service for automated migration of a given site. -# Add SITE_NAME to .env # Compose extension fields of base compose.yaml. See https://github.com/frappe/frappe_docker/blob/main/compose.yaml # Needed for merging compose files. @@ -30,16 +29,16 @@ services: - -c command: - > - if [ -z "$$SITE_NAME" ]; then - echo "[migrator] SITE_NAME is not set"; - exit 1; + if [ "$$MIGRATE_SITES" != "true" ]; then + echo "[migrator] Migration disabled"; + exit 0; fi; - if [ -d "sites/$$SITE_NAME" ]; then - echo "[migrator] Migrating $$SITE_NAME"; - bench --site $$SITE_NAME migrate; - else - echo "[migrator] Site $$SITE_NAME not found, skipping migrate"; - fi + if [ -z "$$(find sites -mindepth 2 -maxdepth 2 -name site_config.json 2>/dev/null)" ]; then + echo "[migrator] No sites found, skipping migration"; + exit 0; + fi; + echo "[migrator] Migrating all sites"; + bench --site all migrate; environment: - SITE_NAME: ${SITE_NAME} - restart: on-failure + MIGRATE_SITES: ${MIGRATE_SITES:-true} + restart: on-failure:5 From 092a3769b15633fdeba5832efdc876d5106c72ee Mon Sep 17 00:00:00 2001 From: jslocomotor <210083531+jslocomotor@users.noreply.github.com> Date: Thu, 30 Apr 2026 23:33:05 +0200 Subject: [PATCH 3/4] docs(overrides): corrected migrator description --- docs/02-setup/05-overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02-setup/05-overrides.md b/docs/02-setup/05-overrides.md index ee3f64af..2cbd9691 100644 --- a/docs/02-setup/05-overrides.md +++ b/docs/02-setup/05-overrides.md @@ -26,7 +26,7 @@ docker compose -f compose.yaml -f overrides/compose.mariadb.yaml -f overrides/co | **Redis** | | | | compose.redis.yaml | Adds Redis service for caching and background job queuing | | | **Services** | | | -| compose.migrator.yaml | Runs a dedicated migration container performing `bench --site all migrate` on a site at every start | Control via `MIGRATE_SITES` - defaults to true | +| compose.migrator.yaml | Runs a dedicated migration container performing `bench --site all migrate` on all sites at every start | Control migration intent with `MIGRATE_SITES` - defaults to true | | **TBD** | **The following overrides are available but lack documentation. If you use them and understand their purpose, please consider contributing to this documentation.** | | | compose.backup-cron.yaml | | | | compose.custom-domain-ssl.yaml | | | From 9432daaaafce319077aa6cab2812cad7d5356942 Mon Sep 17 00:00:00 2001 From: jslocomotor <210083531+jslocomotor@users.noreply.github.com> Date: Sun, 3 May 2026 21:06:04 +0200 Subject: [PATCH 4/4] docs(env): added migration service variable description --- docs/02-setup/04-env-variables.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/02-setup/04-env-variables.md b/docs/02-setup/04-env-variables.md index ab07da67..561ee6d2 100644 --- a/docs/02-setup/04-env-variables.md +++ b/docs/02-setup/04-env-variables.md @@ -140,3 +140,11 @@ Use these variables when running behind a reverse proxy or load balancer: | `UPSTREAM_REAL_IP_ADDRESS` | Trusted upstream IP address for real IP detection | `127.0.0.1` | | `UPSTREAM_REAL_IP_HEADER` | Request header containing client IP | `X-Forwarded-For` | | `UPSTREAM_REAL_IP_RECURSIVE` | Enable recursive IP search | `off` | + +--- + +## Migration Service + +| Variable | Purpose | Default | Allowed Values | +| --------------- | ------------------------------- | -------------------------- | ---------------- | +| `MIGRATE_SITES` | Switch auto migration on or off | `true` - auto migration on | `true` , `false` |