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:
git.prothmann.com/christian/erpnexthp
The image contains ERPNext/Frappe v16 together with the required custom applications.
Current custom applications include:
manufacturing_utilities
eu_einvoice
Legacy applications such as the old standalone:
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:
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:
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:
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:
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:
bench generate-pot-file --app manufacturing_utilities
Then update the existing language .po files:
bench update-po-files --app manufacturing_utilities
The usual workflow is therefore:
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:
bench create-po-file de --app manufacturing_utilities
Afterwards, normally use:
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:
msgid "Manufacturing"
msgstr "Fertigung"
Do not modify the msgid.
Only modify the corresponding:
msgstr
7. Important translation rule
Frappe's translation extractor needs literal strings.
Good:
__("Manufacturing");
Good:
_("Manufacturing")
Bad:
__(status);
because the extractor cannot know which value status will contain.
For dynamic status values, expose the possible strings explicitly:
const statusLabels = {
Draft: __("Draft"),
"To Transfer": __("To Transfer"),
"Material Transferred": __("Material Transferred"),
};
The Manufacturing Overview additionally has:
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:
bench compile-po-to-mo --app manufacturing_utilities
When working in development, also rebuild the application assets:
bench build --app manufacturing_utilities
Then clear the site cache:
bench --site development.localhost clear-cache
A useful complete translation update sequence is:
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:
git status
Commit the final changes:
git add .
git commit -m "Update Manufacturing Utilities"
Push the repository:
git push
The Docker build should always use committed source code.
10. Docker image architecture
Development/build machine:
MacBook Pro M1 Pro
arm64
Production:
Debian
linux/amd64
Therefore the image must be built for:
linux/amd64
The build process uses Docker Buildx.
Conceptually:
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:
16.55.0
Result:
git.prothmann.com/christian/erpnexthp:16.55.0
Normal build:
./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:
./build.sh --tag 16.55.0-no-legacy
This creates:
git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy
Useful examples:
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:
libcups2-dev
Required Python package:
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:
bench pip show pycups
14. Build the image
Run the build from the Mac.
Normal example:
./build.sh
Custom tag example:
./build.sh --tag 16.55.0-no-legacy
The final image should exist locally as:
git.prothmann.com/christian/erpnexthp:<TAG>
Verify:
docker images | grep erpnexthp
15. Push image to Gitea
Push the finished image:
docker push git.prothmann.com/christian/erpnexthp:<TAG>
Example:
docker push git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy
The Gitea container registry is:
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:
docker compose ps
Check the currently configured image/tag:
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:
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:
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:
docker compose pull
This downloads the configured image from Gitea.
Verify that the expected image exists:
docker images | grep erpnexthp
20. Start/recreate the containers
Apply the updated image:
docker compose up -d
Check:
docker compose ps
All expected ERPNext services should be running.
Typical services include:
backend
frontend
websocket
worker
queue
scheduler
redis
mariadb
Actual names depend on the current Compose configuration.
21. Run migrations
After updating the containers:
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:
docker compose exec backend \
bench --site erp.prothmann.com clear-cache
If website cache is relevant:
docker compose exec backend \
bench --site erp.prothmann.com clear-website-cache
23. Check installed applications
Verify that the expected apps are installed:
docker compose exec backend \
bench --site erp.prothmann.com list-apps
Expected relevant applications include:
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:
docker compose exec backend \
bench --site erp.prothmann.com uninstall-app <app_name>
Then run:
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:
docker compose exec backend \
bench --site erp.prothmann.com scheduler status
If necessary:
docker compose exec backend \
bench --site erp.prothmann.com enable-scheduler
25. Check worker/container health
Check:
docker compose ps
Then inspect recent logs:
docker compose logs --tail=100 backend
Worker logs:
docker compose logs --tail=100 worker
Scheduler:
docker compose logs --tail=100 scheduler
Websocket:
docker compose logs --tail=100 websocket
Service names may differ slightly depending on Compose.
26. Production verification checklist
After deployment, test at minimum:
[ ] 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:
bench --site development.localhost \
export-fixtures \
--app manufacturing_utilities
Then:
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
bench generate-pot-file --app manufacturing_utilities
bench update-po-files --app manufacturing_utilities
Compile translations
bench compile-po-to-mo --app manufacturing_utilities
Rebuild assets
bench build --app manufacturing_utilities
Clear dev cache
bench --site development.localhost clear-cache
Complete translation refresh
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:
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:
git add .
git commit -m "Prepare ERPNext production update"
git push
Then build the image.
30. Full production deployment sequence
Typical deployment:
# 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:
- Change
CUSTOM_TAGin.envback to the previous known-good image.
Example:
CUSTOM_TAG=16.55.0
Then:
docker compose pull
docker compose up -d
Check:
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:
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:
docker compose pull
docker compose up -d
Persistent volumes must remain untouched.
33. Production data that must remain unchanged
During normal image updates, preserve:
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:
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
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:
./build.sh
Custom:
./build.sh --tag 16.55.0-no-legacy
Push:
docker push \
git.prothmann.com/christian/erpnexthp:16.55.0-no-legacy
Production
Set:
CUSTOM_TAG=16.55.0-no-legacy
Then:
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:
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.