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