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:

  1. Change CUSTOM_TAG in .env back 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.

S
Description
No description provided
Readme
62 KiB
0 Stars 1 Watchers 0 Forks
Languages
Shell 100%