Updated README

This commit is contained in:
Christian Anetzberger committed 2026-11-14 15:58:26 +01:00
1 parent 83f30d789a
commit 50c2e024a3
1 file changed
+184 -531
+184 -531
View File
@@ -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: The normal update sequence is:
@@ -50,8 +50,8 @@ The normal update sequence is:
4. Commit changes 4. Commit changes
5. Build Docker image on Mac 5. Build Docker image on Mac
6. Push image to Gitea 6. Push image to Gitea
7. Update image tag on production server 7. Back up production and record the rollback target
8. Pull image 8. Select the tag, regenerate and validate Compose on hyp1, then pull
9. Start updated containers 9. Start updated containers
10. Run bench migrate 10. Run bench migrate
11. Clear cache 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. 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. 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. 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. 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: 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. 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. 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. 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: After editing `.po` files:
@@ -241,11 +241,12 @@ Then clear the site cache:
bench --site development.localhost clear-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 ```bash
bench generate-pot-file --app manufacturing_utilities bench generate-pot-file --app manufacturing_utilities
bench update-po-files --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 compile-po-to-mo --app manufacturing_utilities
bench build --app manufacturing_utilities bench build --app manufacturing_utilities
bench --site development.localhost clear-cache 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: Make sure the repository is clean:
@@ -266,7 +267,8 @@ git status
Commit the final changes: Commit the final changes:
```bash ```bash
git add . git add -p
# Explicitly stage any new fixture or locale files after review.
git commit -m "Update Manufacturing Utilities" 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: 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. The normal image tag should match the ERPNext version.
@@ -339,13 +341,13 @@ Normal build:
./build.sh ./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. 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. 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. 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. Run the build from the Mac.
@@ -426,20 +428,23 @@ The final image should exist locally as:
git.prothmann.com/christian/erpnexthp:<TAG> git.prothmann.com/christian/erpnexthp:<TAG>
``` ```
Verify: Set `IMAGE` to the full reference for the tag you just built. Require `linux/amd64` in the inspection output.
```bash ```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: Push the finished image:
```bash ```bash
docker push git.prothmann.com/christian/erpnexthp:<TAG> docker login git.prothmann.com
docker push "$IMAGE"
``` ```
Example: Example:
@@ -454,594 +459,242 @@ The Gitea container registry is:
git.prothmann.com/christian/erpnexthp 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 ```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 ```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. 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.
That tag is the quickest rollback target.
---
# 17. Backup before deployment
Before a production update, create an ERPNext backup:
```bash ```bash
docker compose exec backend \ read -r -p 'Existing production Compose project name: ' COMPOSE_PROJECT
bench --site erp.prothmann.com backup --with-files 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.
--- 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:
# 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 ```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. 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.
Verify that the expected image exists:
```bash ```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"
``` ```
--- Stop if that block fails. Record the recovery directory, then back up the site:
# 20. Start/recreate the containers
Apply the updated image:
```bash ```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 ```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. Confirm the checkout is the official `frappe/frappe_docker` source and the intended branch, with no unexpected local changes. Then update it.
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 ```bash
docker compose exec backend \ git pull --ff-only && git rev-parse HEAD
bench --site erp.prothmann.com migrate
``` ```
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 ### Select the release and render a candidate
- 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 ```bash
docker compose exec backend \ cd /srv/docker/erpnext-16
bench --site erp.prothmann.com clear-cache 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 ```bash
docker compose exec backend \ candidate="$(mktemp "$PWD/docker-compose.generated.XXXXXX.yml")" &&
bench --site erp.prothmann.com clear-website-cache 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 ### Validate the candidate with the local override
Verify that the expected apps are installed:
```bash ```bash
docker compose exec backend \ candidate_dc() {
bench --site erp.prothmann.com list-apps 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 - 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.
frappe - 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.
erpnext - The existing Compose project and external network names, Traefik labels, host routing for `erp.prothmann.com`, ports and proxy attachment remain correct.
manufacturing_utilities - 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.
eu_einvoice
```
Legacy apps should only be removed after their functionality and required data have been migrated. After the review:
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 ```bash
docker compose exec backend \ mv -- "$candidate" docker-compose.yml
bench --site erp.prothmann.com uninstall-app <app_name> 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 ```bash
docker compose exec backend \ erp_dc up -d --pull never
bench --site erp.prothmann.com migrate erp_dc ps -a
``` ```
Only after that should the app be removed from future images. 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.
---
# 24. Check scheduler
Verify that the scheduler is enabled:
```bash ```bash
docker compose exec backend \ erp_dc exec backend bench --site erp.prothmann.com migrate
bench --site erp.prothmann.com scheduler status
``` ```
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 ```bash
docker compose exec backend \ erp_dc exec backend bench --site erp.prothmann.com clear-cache
bench --site erp.prothmann.com enable-scheduler # 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
``` ```
--- 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:
# 25. Check worker/container health
Check:
```bash ```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 ```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 **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.
docker compose logs --tail=100 worker
```
Scheduler: ## Release checklist
```bash 1. Export fixtures when changed, refresh Gettext catalogs, translate, compile, test and push the source.
docker compose logs --tail=100 scheduler 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 - [Frappe v16 Gettext command definitions](https://github.com/frappe/frappe/blob/version-16/frappe/commands/gettext.py)
docker compose logs --tail=100 websocket - [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/)
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.