# 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.