Files
erpnexthp/README.md
T
2026-11-14 15:47:51 +01:00

1048 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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:<TAG>
```
Verify:
```bash
docker images | grep erpnexthp
```
---
# 15. Push image to Gitea
Push the finished image:
```bash
docker push git.prothmann.com/christian/erpnexthp:<TAG>
```
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 <app_name>
```
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.