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` | diff --git a/docs/02-setup/05-overrides.md b/docs/02-setup/05-overrides.md index c81bf153..2cbd9691 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 --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 | | | | 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..8a96107f --- /dev/null +++ b/overrides/compose.migrator.yaml @@ -0,0 +1,44 @@ +# Provides a service for automated migration of a given site. + +# 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 [ "$$MIGRATE_SITES" != "true" ]; then + echo "[migrator] Migration disabled"; + exit 0; + 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: + MIGRATE_SITES: ${MIGRATE_SITES:-true} + restart: on-failure:5