From 66c45d13529a7f8ed1b507cd15e1a37963e4a348 Mon Sep 17 00:00:00 2001 From: Christian Anetzberger Date: Sat, 14 Nov 2026 15:47:51 +0100 Subject: [PATCH] Added README --- README.md | 1047 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1047 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2bd2fc5 --- /dev/null +++ b/README.md @@ -0,0 +1,1047 @@ +# ERPNext v16 – Build, Update & Deployment + +This document describes the complete update process for the custom ERPNext v16 installation, including: + +- application updates +- fixture exports +- translation generation and maintenance +- Docker image builds +- custom image tags +- pushing images to Gitea +- production deployment +- database migrations +- verification +- rollback + +The production image is stored in: + +```text +git.prothmann.com/christian/erpnexthp +``` + +The image contains ERPNext/Frappe v16 together with the required custom applications. + +Current custom applications include: + +```text +manufacturing_utilities +eu_einvoice +``` + +Legacy applications such as the old standalone: + +```text +manufacturing_overview +label_printing +``` + +should not be included in new clean builds once their functionality has been migrated into `manufacturing_utilities`. + +--- + +# 1. General workflow + +The normal update sequence is: + +```text +1. Finish development +2. Export fixtures +3. Update translations +4. Commit changes +5. Build Docker image on Mac +6. Push image to Gitea +7. Update image tag on production server +8. Pull image +9. Start updated containers +10. Run bench migrate +11. Clear cache +12. Verify scheduler/workers +13. Test ERPNext +``` + +Do not build the ERPNext image directly on the production server. + +The image is built on the Mac and production only pulls the finished image. + +--- + +# 2. Development preparation + +Before creating a new Docker image, make sure all application changes are committed. + +From the bench/app development environment, check: + +```bash +git status +``` + +Review all changed files before continuing. + +--- + +# 3. Export fixtures + +Fixtures must be exported whenever something managed through ERPNext has changed that belongs in the app. + +For `manufacturing_utilities`: + +```bash +bench --site development.localhost export-fixtures --app manufacturing_utilities +``` + +This includes, among other things, exported Custom HTML Blocks and Custom Fields configured in `hooks.py`. + +For example, the Manufacturing Overview Custom HTML Block is exported through the app fixtures. + +After exporting: + +```bash +git status +``` + +Check that the expected fixture files changed. + +Then commit them together with the related code. + +--- + +# 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 + +Whenever new translatable strings are added: + +```bash +bench generate-pot-file --app manufacturing_utilities +``` + +Then update the existing language `.po` files: + +```bash +bench update-po-files --app manufacturing_utilities +``` + +The usual workflow is therefore: + +```bash +bench generate-pot-file --app manufacturing_utilities +bench update-po-files --app manufacturing_utilities +``` + +--- + +# 5. Creating a new language file + +This is only required once for a new language. + +For German: + +```bash +bench create-po-file de --app manufacturing_utilities +``` + +Afterwards, normally use: + +```bash +bench update-po-files --app manufacturing_utilities +``` + +instead. + +--- + +# 6. Editing German translations + +The German `.po` file is stored inside the application locale directory. + +Translate entries such as: + +```po +msgid "Manufacturing" +msgstr "Fertigung" +``` + +Do not modify the `msgid`. + +Only modify the corresponding: + +```text +msgstr +``` + +--- + +# 7. Important translation rule + +Frappe's translation extractor needs literal strings. + +Good: + +```javascript +__("Manufacturing"); +``` + +Good: + +```python +_("Manufacturing") +``` + +Bad: + +```javascript +__(status); +``` + +because the extractor cannot know which value `status` will contain. + +For dynamic status values, expose the possible strings explicitly: + +```javascript +const statusLabels = { + Draft: __("Draft"), + "To Transfer": __("To Transfer"), + "Material Transferred": __("Material Transferred"), +}; +``` + +The Manufacturing Overview additionally has: + +```text +manufacturing_utilities/manufacturing_overview/translations.py +``` + +which exposes Custom HTML Block strings to Frappe's translation extractor. + +Whenever a new user-facing string is introduced into the Manufacturing Overview, add it there as well. + +--- + +# 8. Compile translations + +After editing `.po` files: + +```bash +bench compile-po-to-mo --app manufacturing_utilities +``` + +When working in development, also rebuild the application assets: + +```bash +bench build --app manufacturing_utilities +``` + +Then clear the site cache: + +```bash +bench --site development.localhost clear-cache +``` + +A useful complete translation update sequence is: + +```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 +``` + +Then hard-refresh the browser. + +--- + +# 9. Before building a production image + +Make sure the repository is clean: + +```bash +git status +``` + +Commit the final changes: + +```bash +git add . +git commit -m "Update Manufacturing Utilities" +``` + +Push the repository: + +```bash +git push +``` + +The Docker build should always use committed source code. + +--- + +# 10. Docker image architecture + +Development/build machine: + +```text +MacBook Pro M1 Pro +arm64 +``` + +Production: + +```text +Debian +linux/amd64 +``` + +Therefore the image must be built for: + +```text +linux/amd64 +``` + +The build process uses Docker Buildx. + +Conceptually: + +```bash +docker buildx build \ + --platform linux/amd64 \ + --load \ + ... +``` + +The existing build script handles this. + +--- + +# 11. Standard image tags + +The normal image tag should match the ERPNext version. + +Example: + +```text +16.55.0 +``` + +Result: + +```text +git.prothmann.com/christian/erpnexthp:16.55.0 +``` + +Normal build: + +```bash +./build.sh +``` + +or whatever default invocation the current build script expects. + +The resulting image should normally use the ERPNext version as its tag. + +--- + +# 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. + +Example: + +```bash +./build.sh --tag 16.55.0-no-legacy +``` + +This creates: + +```text +git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy +``` + +Useful examples: + +```text +16.55.0-test +16.55.0-no-legacy +16.55.0-migration-test +16.55.0-clean +``` + +A custom tag should never silently overwrite the normal ERPNext-version tag unless this is explicitly intended. + +This makes rollback and parallel testing much easier. + +--- + +# 13. Important image dependencies + +The image must include the dependencies required for network printing. + +Required Debian package: + +```text +libcups2-dev +``` + +Required Python package: + +```text +pycups +``` + +This must be baked into the Docker image. + +Do not rely on installing these manually inside a running production container because the installation would disappear when the container is recreated. + +To verify pycups inside a container: + +```bash +bench pip show pycups +``` + +--- + +# 14. Build the image + +Run the build from the Mac. + +Normal example: + +```bash +./build.sh +``` + +Custom tag example: + +```bash +./build.sh --tag 16.55.0-no-legacy +``` + +The final image should exist locally as: + +```text +git.prothmann.com/christian/erpnexthp: +``` + +Verify: + +```bash +docker images | grep erpnexthp +``` + +--- + +# 15. Push image to Gitea + +Push the finished image: + +```bash +docker push git.prothmann.com/christian/erpnexthp: +``` + +Example: + +```bash +docker push git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy +``` + +The Gitea container registry is: + +```text +git.prothmann.com/christian/erpnexthp +``` + +Production should only pull this image. + +--- + +# 16. Production preparation + +SSH into the production Debian server. + +Move to the ERPNext v16 Compose directory. + +Before changing anything, check the currently running containers: + +```bash +docker compose ps +``` + +Check the currently configured image/tag: + +```bash +grep -E 'ERPNEXT_VERSION|CUSTOM_TAG' .env +``` + +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: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com backup --with-files +``` + +For significant upgrades, verify that the backup completed successfully before continuing. + +--- + +# 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: + +```bash +docker compose pull +``` + +This downloads the configured image from Gitea. + +Verify that the expected image exists: + +```bash +docker images | grep erpnexthp +``` + +--- + +# 20. Start/recreate the containers + +Apply the updated image: + +```bash +docker compose up -d +``` + +Check: + +```bash +docker compose ps +``` + +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: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com migrate +``` + +This is important whenever: + +- 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: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com clear-cache +``` + +If website cache is relevant: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com clear-website-cache +``` + +--- + +# 23. Check installed applications + +Verify that the expected apps are installed: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com list-apps +``` + +Expected relevant applications include: + +```text +frappe +erpnext +manufacturing_utilities +eu_einvoice +``` + +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: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com uninstall-app +``` + +Then run: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com migrate +``` + +Only after that should the app be removed from future images. + +--- + +# 24. Check scheduler + +Verify that the scheduler is enabled: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com scheduler status +``` + +If necessary: + +```bash +docker compose exec backend \ + bench --site erp.prothmann.com enable-scheduler +``` + +--- + +# 25. Check worker/container health + +Check: + +```bash +docker compose ps +``` + +Then inspect recent logs: + +```bash +docker compose logs --tail=100 backend +``` + +Worker logs: + +```bash +docker compose logs --tail=100 worker +``` + +Scheduler: + +```bash +docker compose logs --tail=100 scheduler +``` + +Websocket: + +```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.