diff --git a/README.md b/README.md index 2bd2fc5..c2580f7 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ should not be included in new clean builds once their functionality has been mig --- -# 1. General workflow +## 1. General workflow The normal update sequence is: @@ -50,8 +50,8 @@ The normal update sequence is: 4. Commit changes 5. Build Docker image on Mac 6. Push image to Gitea -7. Update image tag on production server -8. Pull image +7. Back up production and record the rollback target +8. Select the tag, regenerate and validate Compose on hyp1, then pull 9. Start updated containers 10. Run bench migrate 11. Clear cache @@ -65,7 +65,7 @@ The image is built on the Mac and production only pulls the finished image. --- -# 2. Development preparation +## 2. Development preparation Before creating a new Docker image, make sure all application changes are committed. @@ -79,7 +79,7 @@ Review all changed files before continuing. --- -# 3. Export fixtures +## 3. Export fixtures Fixtures must be exported whenever something managed through ERPNext has changed that belongs in the app. @@ -105,13 +105,13 @@ Then commit them together with the related code. --- -# 4. Translation workflow +## 4. Translation workflow ERPNext/Frappe v16 uses Gettext `.po` translation files. Translations for `manufacturing_utilities` should be stored in the application repository rather than maintained manually through the ERPNext Translation DocType. -## 4.1 Generate/update translatable strings +### 4.1 Generate/update translatable strings Whenever new translatable strings are added: @@ -134,7 +134,7 @@ bench update-po-files --app manufacturing_utilities --- -# 5. Creating a new language file +## 5. Creating a new language file This is only required once for a new language. @@ -154,7 +154,7 @@ instead. --- -# 6. Editing German translations +## 6. Editing German translations The German `.po` file is stored inside the application locale directory. @@ -175,7 +175,7 @@ msgstr --- -# 7. Important translation rule +## 7. Important translation rule Frappe's translation extractor needs literal strings. @@ -221,7 +221,7 @@ Whenever a new user-facing string is introduced into the Manufacturing Overview, --- -# 8. Compile translations +## 8. Compile translations After editing `.po` files: @@ -241,11 +241,12 @@ Then clear the site cache: bench --site development.localhost clear-cache ``` -A useful complete translation update sequence is: +Run the catalog refresh, edit the PO files, then compile and test. ```bash bench generate-pot-file --app manufacturing_utilities bench update-po-files --app manufacturing_utilities +# Edit and review msgstr values before compiling. bench compile-po-to-mo --app manufacturing_utilities bench build --app manufacturing_utilities bench --site development.localhost clear-cache @@ -255,7 +256,7 @@ Then hard-refresh the browser. --- -# 9. Before building a production image +## 9. Before building a production image Make sure the repository is clean: @@ -266,7 +267,8 @@ git status Commit the final changes: ```bash -git add . +git add -p +# Explicitly stage any new fixture or locale files after review. git commit -m "Update Manufacturing Utilities" ``` @@ -280,7 +282,7 @@ The Docker build should always use committed source code. --- -# 10. Docker image architecture +## 10. Docker image architecture Development/build machine: @@ -317,7 +319,7 @@ The existing build script handles this. --- -# 11. Standard image tags +## 11. Standard image tags The normal image tag should match the ERPNext version. @@ -339,13 +341,13 @@ Normal build: ./build.sh ``` -or whatever default invocation the current build script expects. +Run from the checkout containing the existing `build.sh`. Its location and current options should be recorded in the release notes after checking the script. The resulting image should normally use the ERPNext version as its tag. --- -# 12. Custom image tags +## 12. Custom image tags Use a custom tag whenever testing a special build or when multiple images based on the same ERPNext release need to coexist. @@ -376,7 +378,7 @@ This makes rollback and parallel testing much easier. --- -# 13. Important image dependencies +## 13. Important image dependencies The image must include the dependencies required for network printing. @@ -404,7 +406,7 @@ bench pip show pycups --- -# 14. Build the image +## 14. Build the image Run the build from the Mac. @@ -426,20 +428,23 @@ The final image should exist locally as: git.prothmann.com/christian/erpnexthp: ``` -Verify: +Set `IMAGE` to the full reference for the tag you just built. Require `linux/amd64` in the inspection output. ```bash -docker images | grep erpnexthp +TAG=16.55.0-no-legacy # Example. Use your actual build tag. +IMAGE="git.prothmann.com/christian/erpnexthp:$TAG" +docker image inspect --format '{{.Os}}/{{.Architecture}} {{.Id}}' "$IMAGE" ``` --- -# 15. Push image to Gitea +## 15. Push image to Gitea Push the finished image: ```bash -docker push git.prothmann.com/christian/erpnexthp: +docker login git.prothmann.com +docker push "$IMAGE" ``` Example: @@ -454,594 +459,242 @@ The Gitea container registry is: git.prothmann.com/christian/erpnexthp ``` -Production should only pull this image. +Use the Gitea credential authorized to publish the package. Record the digest printed by `docker push`, and keep the previously deployed tag and digest available. Production pulls the published image. --- -# 16. Production preparation +## 16. Release checks before touching hyp1 -SSH into the production Debian server. +- Record the release tag and registry digest, Frappe/ERPNext and custom app refs, build checkout and command, and the app manifest used by the build. Use a fresh tag for each distinct image, including rebuilds against the same ERPNext release. +- Confirm that the actual build inputs fetch the commits you pushed. Check the image contains `frappe`, `erpnext`, `manufacturing_utilities` and `eu_einvoice`, with compiled translations and built assets. Verify `bench pip show pycups` and an actual `import cups` with the Bench Python environment in the resulting image. +- On a restored test copy, run the migration and acceptance checks below before a significant version change or app removal. Keep test integrations from sending production mail, print jobs or e-invoices. -Move to the ERPNext v16 Compose directory. +### Legacy apps -Before changing anything, check the currently running containers: +Before deploying an image without `manufacturing_overview` or `label_printing`, check `list-apps` on every site served by this stack. If either app is still installed, use a transitional image that contains it while moving and validating any required data, fixtures and functionality. Rehearse on a restored copy and take a fresh backup before uninstalling in production. Uninstall can delete app-owned DocTypes and data. + +On the image that still contains the app, inspect the removal first. Example for one app on the production site: ```bash -docker compose ps +erp_dc exec backend bench --site erp.prothmann.com uninstall-app --help +erp_dc exec backend bench --site erp.prothmann.com uninstall-app manufacturing_overview --dry-run ``` -Check the currently configured image/tag: +After reviewing the dry run and approving the deletions, run the uninstall without `--dry-run`, migrate, and confirm with `list-apps`. Repeat separately for `label_printing` if applicable. Build or deploy the clean image once every affected site is ready. Treat uninstall as a database-changing operation for rollback purposes. + +## 17. hyp1 preflight and backup + +SSH to `hyp1` with the usual production account. Run the following in Bash, from the deployment directory. Keep your session open or redefine the function after reconnecting. ```bash -grep -E 'ERPNEXT_VERSION|CUSTOM_TAG' .env +cd /srv/docker/erpnext-16 +docker compose version +docker compose ls +docker compose ps -a ``` -It is useful to note the currently running image tag before updating. - -That tag is the quickest rollback target. - ---- - -# 17. Backup before deployment - -Before a production update, create an ERPNext backup: +Confirm the running project name from `docker compose ls` and its configuration files. If the default invocation does not find the expected stack, resolve the project name before continuing. Enter the existing project name when prompted. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com backup --with-files +read -r -p 'Existing production Compose project name: ' COMPOSE_PROJECT +erp_dc() { + docker compose --project-name "${COMPOSE_PROJECT:?Set the existing project name}" \ + --project-directory /srv/docker/erpnext-16 --env-file .env \ + -f docker-compose.yml -f docker-compose.override.yml "$@" +} +erp_dc ps -a +erp_dc config --images +erp_dc config --services +erp_dc exec backend bench --site erp.prothmann.com list-apps +erp_dc exec backend bench --site erp.prothmann.com scheduler status ``` -For significant upgrades, verify that the backup completed successfully before continuing. +Record the running images and digests (including DB and Redis), service names, Compose project, actual volume and network names, installed apps and scheduler state. Use running container inspection if configured and running images differ. Check disk space and that the external Traefik proxy network exists. Check for extra sites before deployment. If the stack serves multiple sites, plan backup, migration and verification for each. ---- - -# 18. Selecting the production image - -Production uses the image tag configured in `.env`. - -For a normal release this may correspond to the ERPNext version. - -For a custom build, set: - -```env -CUSTOM_TAG=16.55.0-no-legacy -``` - -Only change the tag required for the new image. - -Do not unnecessarily modify database passwords, Redis configuration, site volumes, networks, or encryption keys during an ordinary application update. - ---- - -# 19. Pull the new image - -On production: +Schedule a maintenance window. Prevent traffic and other writes, let in-flight requests and background jobs finish, and pause scheduling if it was active. Record which settings you change so you can restore them. For example: ```bash -docker compose pull +erp_dc exec backend bench --site erp.prothmann.com set-maintenance-mode on +erp_dc exec backend bench --site erp.prothmann.com scheduler pause +erp_dc exec backend bench --site erp.prothmann.com doctor +erp_dc exec backend bench --site erp.prothmann.com ready-for-migration ``` -This downloads the configured image from Gitea. - -Verify that the expected image exists: +Check existing worker queues and coordinate integrations that can still write before taking the final backup. Leave services required for draining jobs running until the drain is complete. ```bash -docker images | grep erpnexthp +umask 077 +RECOVERY_DIR="$(mktemp -d "$PWD/recovery-$(date +%Y%m%d-%H%M%S)-XXXXXX")" && + cp -p .env docker-compose.yml docker-compose.override.yml "$RECOVERY_DIR/" && + git -C /srv/docker/frappe_docker-source rev-parse HEAD > "$RECOVERY_DIR/frappe_docker-revision" ``` ---- - -# 20. Start/recreate the containers - -Apply the updated image: +Stop if that block fails. Record the recovery directory, then back up the site: ```bash -docker compose up -d +erp_dc exec backend bench --site erp.prothmann.com backup --with-files +erp_dc exec backend ls -lh sites/erp.prothmann.com/private/backups/ ``` -Check: +Copy the exact files from this run (database, public and private files, and site configuration) out of the sites volume. For each file, use `erp_dc cp backend:sites/erp.prothmann.com/private/backups/ACTUAL_FILENAME "$RECOVERY_DIR/"`, replacing `ACTUAL_FILENAME` with the name reported by Bench. Expect dated files, and verify that the database and file archives are readable and nonempty. Verify that the recovery set includes the original `site_config.json` and its encryption key. Save the original configuration separately if the backup omits it. Preserve `sites/common_site_config.json` and any referenced secrets or extra environment files with the deployment snapshot. Store an access-restricted copy away from hyp1 and its Docker volumes, with checksums and a recorded restore location. Confirm you can retrieve it before proceeding. + +## 18. Generate and validate production Compose on hyp1 + +### Update the official upstream checkout ```bash -docker compose ps +cd /srv/docker/frappe_docker-source +git remote -v +git status --short +git branch --show-current ``` -All expected ERPNext services should be running. - -Typical services include: - -```text -backend -frontend -websocket -worker -queue -scheduler -redis -mariadb -``` - -Actual names depend on the current Compose configuration. - ---- - -# 21. Run migrations - -After updating the containers: +Confirm the checkout is the official `frappe/frappe_docker` source and the intended branch, with no unexpected local changes. Then update it. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com migrate +git pull --ff-only && git rev-parse HEAD ``` -This is important whenever: +If the pull fails, resolve the checkout before generating anything. Record the resulting commit and review changes to the upstream base, MariaDB and Redis overrides since the deployed revision. A source pull can change infrastructure image versions, health checks, mount paths, and startup dependencies. Keep the existing DB and Redis versions or digests for an app-only release. Schedule and test intentional infrastructure upgrades separately. -- DocTypes changed -- Custom Fields changed -- fixtures changed -- application patches were added -- ERPNext/Frappe version changed -- app schemas changed - -Do not skip `bench migrate` after deploying application updates. - ---- - -# 22. Clear production cache - -After migration: +### Select the release and render a candidate ```bash -docker compose exec backend \ - bench --site erp.prothmann.com clear-cache +cd /srv/docker/erpnext-16 +grep -nE '^(CUSTOM_TAG|CUSTOM_IMAGE|ERPNEXT_VERSION)=' .env ``` -If website cache is relevant: +Set `CUSTOM_TAG` in `.env` to the exact pushed tag, for example `CUSTOM_TAG=16.55.0-no-legacy`. Check how the override selects the image. If it hard-codes a tag, update its corresponding image references. Preserve real DB credentials, Traefik routing, external proxy network, and production volume mappings. Check for inherited shell variables that would override values from `.env`, especially image and tag variables. + +Run from `/srv/docker/erpnext-16`. A temporary file keeps a failed render from truncating the current base. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com clear-website-cache +candidate="$(mktemp "$PWD/docker-compose.generated.XXXXXX.yml")" && + DB_PASSWORD=COMPOSE_TEMPLATE_ONLY docker compose \ + --env-file .env \ + -f /srv/docker/frappe_docker-source/compose.yaml \ + -f /srv/docker/frappe_docker-source/overrides/compose.mariadb.yaml \ + -f /srv/docker/frappe_docker-source/overrides/compose.redis.yaml \ + config > "$candidate" && + test -s "$candidate" ``` ---- +Stop if rendering fails. `COMPOSE_TEMPLATE_ONLY` supplies `DB_PASSWORD` for that render command alone. The local `docker-compose.override.yml` supplies the real production value. Check the merged result for any surviving placeholder, including DB environment variables and health checks. Correct the override before applying if any remain. Always regenerate after a tag change when the base resolves images from `.env`. -# 23. Check installed applications - -Verify that the expected apps are installed: +### Validate the candidate with the local override ```bash -docker compose exec backend \ - bench --site erp.prothmann.com list-apps +candidate_dc() { + docker compose --project-name "${COMPOSE_PROJECT:?Set the existing project name}" \ + --project-directory /srv/docker/erpnext-16 --env-file .env \ + -f "${candidate:?Render the candidate first}" -f docker-compose.override.yml "$@" +} +candidate_dc config --quiet +candidate_dc config --images +candidate_dc config --services ``` -Expected relevant applications include: +Inspect the full `candidate_dc config` privately. It can contain real secrets. Compare with the saved deployment and current runtime. Confirm: -```text -frappe -erpnext -manufacturing_utilities -eu_einvoice -``` +- Every ERPNext service that uses the custom image resolves to the intended Gitea reference, including backend, frontend, websocket, scheduler, workers and the configurator where applicable. +- MariaDB and Redis image versions, service endpoints and health checks match the release plan. Use the same persistent MariaDB, Redis and sites volumes and verify any bind mount paths. Rendered relative paths may have been resolved against the upstream source checkout. +- The existing Compose project and external network names, Traefik labels, host routing for `erp.prothmann.com`, ports and proxy attachment remain correct. +- The local override supplies the effective production DB settings and no `COMPOSE_TEMPLATE_ONLY` remains in the merged result. Check existing site DB credentials and encryption keys are preserved. -Legacy apps should only be removed after their functionality and required data have been migrated. - -Do not simply remove an app from the Docker build while it is still installed on the site. - -First uninstall it correctly if required. - -Example: +After the review: ```bash -docker compose exec backend \ - bench --site erp.prothmann.com uninstall-app +mv -- "$candidate" docker-compose.yml +erp_dc config --quiet +erp_dc config --images +docker login git.prothmann.com +erp_dc pull ``` -Then run: +Use a Gitea credential authorized to pull the private package. If pull fails, stop before starting the update. Inspect `docker image inspect FULL_NEW_IMAGE_REFERENCE` using the actual Gitea reference and verify its repository digest against the push record. Recheck MariaDB and Redis digests if their tags are mutable. Keep the old image available. + +## 19. Apply, migrate and verify + +In the maintenance window, apply the validated stack using the images just pulled and checked. The explicit pull policy prevents another registry fetch during startup. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com migrate +erp_dc up -d --pull never +erp_dc ps -a ``` -Only after that should the app be removed from future images. - ---- - -# 24. Check scheduler - -Verify that the scheduler is enabled: +Confirm backend readiness and check database/Redis health. An exited configurator can be expected if it completed successfully. Check its exit code and logs. Keep production writes blocked while migration runs. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com scheduler status +erp_dc exec backend bench --site erp.prothmann.com migrate ``` -If necessary: +If migration fails, keep maintenance active and diagnose before proceeding. Capture the failing patch or fixture and relevant logs. A failed migration can already have changed schema or data. Avoid skipping failing patches as part of routine recovery. ```bash -docker compose exec backend \ - bench --site erp.prothmann.com enable-scheduler +erp_dc exec backend bench --site erp.prothmann.com clear-cache +# When website cache is relevant: +erp_dc exec backend bench --site erp.prothmann.com clear-website-cache +erp_dc exec backend bench --site erp.prothmann.com list-apps +erp_dc ps -a +erp_dc logs --since=15m --tail=100 ``` ---- - -# 25. Check worker/container health - -Check: +Confirm running image identities against the release record and check for DB, Redis, permission, asset, fixture, websocket and queue errors. Use `erp_dc config --services` to find actual service names and narrow logs as needed. Confirm scheduler and worker processes are up. Restore maintenance mode and scheduler pause to their recorded settings after migration and infrastructure checks pass. For a site that was originally live with an unpaused scheduler: ```bash -docker compose ps +erp_dc exec backend bench --site erp.prothmann.com set-maintenance-mode off +erp_dc exec backend bench --site erp.prothmann.com scheduler resume +erp_dc exec backend bench --site erp.prothmann.com scheduler status +erp_dc exec backend bench --site erp.prothmann.com doctor ``` -Then inspect recent logs: +If scheduling is unexpectedly disabled, diagnose its settings. Use `bench --site erp.prothmann.com enable-scheduler` inside the backend only when the site is intended to schedule jobs and its scheduler is disabled. Verify a known safe background job completes and the expected workers are online. If traffic was restricted externally, reopen it once smoke tests pass. + +### Acceptance checklist + +- [ ] HTTPS, login, Desk, static assets and realtime features work through Traefik. +- [ ] Manufacturing Utilities workspace and Manufacturing Overview load. +- [ ] PRO / Work Order and Sales Order links work. Planned End Date sorting is correct. +- [ ] Subcontracting cards, draft Purchase Orders and submitted subcontracting orders appear. +- [ ] German translations appear after selecting German and hard-refreshing. Check a newly translated Manufacturing Overview label. +- [ ] Label Composer opens, preview renders, and an authorized test label prints on the network printer. +- [ ] E-invoice functionality opens and passes a non-sending smoke test. +- [ ] Scheduler is in its intended state, workers process jobs, and logs show no new recurring errors. +- [ ] Release record has the deployed digest, upstream Compose revision, backup location, and verification result. + +## 20. Rollback and recovery + +Keep writes blocked while deciding how to recover. Capture service status, logs and the failing release details. If the failure happened before any schema, data or infrastructure change and the old image is compatible with current state, restore the saved **pair** of Compose files and saved `.env` from the same release. Include any other changed deployment files and preserve file permissions. Verify the previous config and image digests before starting it. ```bash -docker compose logs --tail=100 backend +cd /srv/docker/erpnext-16 +# Set RECOVERY_DIR to the verified pre-release snapshot if reconnecting. +cp -p "${RECOVERY_DIR:?Set the recovery directory}/.env" \ + "$RECOVERY_DIR/docker-compose.yml" \ + "$RECOVERY_DIR/docker-compose.override.yml" . +erp_dc config --quiet +erp_dc config --images +# Pull only if needed, and verify the previous digest before applying. +erp_dc up -d --pull never +erp_dc ps -a ``` -Worker logs: +A prior image cannot undo `migrate`, app uninstall, data patches, or MariaDB on-disk upgrades. If the old image is incompatible with the modified state, preserve a copy of the failed state and establish what writes occurred since the backup. Restore the verified pre-update SQL and both file archives together with the matching site configuration/encryption key, using the old compatible application and database versions. Confirm the exact `bench --site erp.prothmann.com restore --help` on that release and rehearse with the saved files on a separate recovery target before overwriting production. For an incompatible MariaDB storage upgrade, recover onto compatible storage rather than starting an older server on the upgraded data directory. Recheck queues and pending integrations before resuming them. Run the acceptance checklist after recovery. -```bash -docker compose logs --tail=100 worker -``` +**Never run `docker compose down -v` during this workflow.** Preserve DB, Redis and sites volumes, public and private files, DB credentials, encryption keys, and Traefik networks. Keep the previous image and recovery artifacts until the release has passed verification. -Scheduler: +## Release checklist -```bash -docker compose logs --tail=100 scheduler -``` +1. Export fixtures when changed, refresh Gettext catalogs, translate, compile, test and push the source. +2. Build on the Mac for `linux/amd64`, verify apps and printing dependencies, push the unique Gitea tag and record its digest. +3. On hyp1 identify the current project, block writes, drain jobs and verify the backup and rollback snapshot. +4. Update the official source checkout, select the new tag, render the base with `COMPOSE_TEMPLATE_ONLY`, then validate it with the production override. +5. Install the validated base, pull, compare digests, run `up -d`, migrate and clear caches. +6. Verify scheduler, workers and application behavior. Restore normal traffic and record the outcome. -Websocket: +## References -```bash -docker compose logs --tail=100 websocket -``` - -Service names may differ slightly depending on Compose. - ---- - -# 26. Production verification checklist - -After deployment, test at minimum: - -```text -[ ] ERPNext login works -[ ] Desk loads normally -[ ] Manufacturing Utilities workspace loads -[ ] Manufacturing Overview loads -[ ] PRO / Work Order links appear -[ ] Sales Order links work -[ ] Planned End Date sorting works -[ ] Subcontracting cards appear -[ ] Draft Purchase Orders appear -[ ] Submitted subcontracting orders appear -[ ] German translations load -[ ] Label Composer opens -[ ] Label preview works -[ ] Network printing works -[ ] Scheduler is running -[ ] Workers are running -``` - ---- - -# 27. Manufacturing Overview fixture updates - -If the Custom HTML Block is changed directly through ERPNext, export the fixture before committing: - -```bash -bench --site development.localhost \ - export-fixtures \ - --app manufacturing_utilities -``` - -Then: - -```bash -git status -``` - -Verify that the Custom HTML Block fixture changed. - -Commit it before building the image. - ---- - -# 28. Development translation quick reference - -Most frequently needed commands: - -## New strings added - -```bash -bench generate-pot-file --app manufacturing_utilities -bench update-po-files --app manufacturing_utilities -``` - -## Compile translations - -```bash -bench compile-po-to-mo --app manufacturing_utilities -``` - -## Rebuild assets - -```bash -bench build --app manufacturing_utilities -``` - -## Clear dev cache - -```bash -bench --site development.localhost clear-cache -``` - -## Complete translation refresh - -```bash -bench generate-pot-file --app manufacturing_utilities -bench update-po-files --app manufacturing_utilities -bench compile-po-to-mo --app manufacturing_utilities -bench build --app manufacturing_utilities -bench --site development.localhost clear-cache -``` - ---- - -# 29. Full pre-build development checklist - -Before creating an image: - -```bash -bench --site development.localhost export-fixtures --app manufacturing_utilities - -bench generate-pot-file --app manufacturing_utilities -bench update-po-files --app manufacturing_utilities -bench compile-po-to-mo --app manufacturing_utilities - -bench build --app manufacturing_utilities -bench --site development.localhost clear-cache - -git status -``` - -Then verify the application in the browser. - -If everything is correct: - -```bash -git add . -git commit -m "Prepare ERPNext production update" -git push -``` - -Then build the image. - ---- - -# 30. Full production deployment sequence - -Typical deployment: - -```bash -# Check current state -docker compose ps - -# Backup -docker compose exec backend \ - bench --site erp.prothmann.com backup --with-files - -# Update CUSTOM_TAG in .env - -# Pull image -docker compose pull - -# Recreate services -docker compose up -d - -# Migrate -docker compose exec backend \ - bench --site erp.prothmann.com migrate - -# Clear cache -docker compose exec backend \ - bench --site erp.prothmann.com clear-cache - -# Verify apps -docker compose exec backend \ - bench --site erp.prothmann.com list-apps - -# Verify scheduler -docker compose exec backend \ - bench --site erp.prothmann.com scheduler status - -# Verify containers -docker compose ps -``` - -Then test ERPNext in the browser. - ---- - -# 31. Rollback - -The reason custom tags are useful is that the previous image remains available. - -If the new image causes problems: - -1. Change `CUSTOM_TAG` in `.env` back to the previous known-good image. - -Example: - -```env -CUSTOM_TAG=16.55.0 -``` - -Then: - -```bash -docker compose pull -docker compose up -d -``` - -Check: - -```bash -docker compose ps -``` - -Be careful after database migrations. - -Rolling back the Docker image does **not automatically roll back database schema/data changes**. - -For an application-only problem, an image rollback may be sufficient. - -For a destructive database migration, restore from the backup created before deployment. - ---- - -# 32. Important Docker warnings - -Never use: - -```bash -docker compose down -v -``` - -during a normal ERPNext update. - -The `-v` option deletes Compose-managed volumes and can destroy persistent database/site data. - -Normal updates should use: - -```bash -docker compose pull -docker compose up -d -``` - -Persistent volumes must remain untouched. - ---- - -# 33. Production data that must remain unchanged - -During normal image updates, preserve: - -```text -database volumes -sites volume -Redis volumes -encryption key -database credentials -site_config.json -private files -public files -Traefik/network configuration -``` - -An application/image update should not require recreating these. - ---- - -# 34. App image requirements - -The production image must include everything needed at runtime. - -Do not manually install permanent dependencies in running containers. - -For example: - -```text -libcups2-dev -pycups -``` - -must be part of the image build. - -If a container is recreated, any manual changes inside it are lost. - ---- - -# 35. Quick update cheat sheet - -## Development - -```bash -bench --site development.localhost export-fixtures --app manufacturing_utilities - -bench generate-pot-file --app manufacturing_utilities -bench update-po-files --app manufacturing_utilities -bench compile-po-to-mo --app manufacturing_utilities - -bench build --app manufacturing_utilities -bench --site development.localhost clear-cache - -git status -git add . -git commit -m "Update Manufacturing Utilities" -git push -``` - -## Build - -Normal: - -```bash -./build.sh -``` - -Custom: - -```bash -./build.sh --tag 16.55.0-no-legacy -``` - -Push: - -```bash -docker push \ - git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy -``` - -## Production - -Set: - -```env -CUSTOM_TAG=16.55.0-no-legacy -``` - -Then: - -```bash -docker compose exec backend \ - bench --site erp.prothmann.com backup --with-files - -docker compose pull -docker compose up -d - -docker compose exec backend \ - bench --site erp.prothmann.com migrate - -docker compose exec backend \ - bench --site erp.prothmann.com clear-cache - -docker compose exec backend \ - bench --site erp.prothmann.com scheduler status - -docker compose ps -``` - -Then verify ERPNext manually. - ---- - -# 36. Recommended rule - -For every production deployment: - -```text -Export → Translate → Commit → Build → Tag → Push → Backup → Pull → Migrate → Verify -``` - -Never deploy uncommitted application changes, and always keep the previous image tag available until the new version has been verified in production. +- [Frappe v16 Gettext command definitions](https://github.com/frappe/frappe/blob/version-16/frappe/commands/gettext.py) +- [Frappe v16 scheduler and worker commands](https://github.com/frappe/frappe/blob/version-16/frappe/commands/scheduler.py) +- [Official frappe_docker Compose overrides](https://github.com/frappe/frappe_docker/blob/main/docs/02-setup/05-overrides.md) +- [Docker Compose config reference](https://docs.docker.com/reference/cli/docker/compose/config/)