Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (56 loc) · 4.17 KB

CLAUDE.md

File metadata and controls

80 lines (56 loc) · 4.17 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Project Does

Bash script collection for managing an ERPNext production deployment on Docker Compose. It orchestrates three separate Docker Compose stacks (Traefik, MariaDB, ERPNext) and a custom image build pipeline.

The production server is accessed via ssh erpnext. All containers run in /opt/erpnext_docker_scripts/ on the server.

Key Commands

All scripts must be run from the project root (they use common.sh which cds to the root and sources .env).

# Deploy a new version (the main workflow)
scripts/erpnext-custom-setup.sh          # builds Docker image
scripts/erpnext-custom-docker.sh down
scripts/erpnext-custom-docker.sh up
scripts/erpnext-backend.sh bench migrate
scripts/erpnext-backend.sh bench build
scripts/erpnext-custom-docker.sh down
scripts/erpnext-custom-docker.sh up

# Run bench commands inside backend container
scripts/erpnext-backend.sh bench --site erp.adomio.com install-app <app>
scripts/erpnext-backend.sh bench --site erp.adomio.com migrate
scripts/erpnext-backend.sh bench --site erp.adomio.com list-apps

# Stack management
scripts/traefik-docker.sh up|down|logs
scripts/mariadb-docker.sh up|down|logs
scripts/erpnext-custom-docker.sh up|down|logs

# Manual backup
scripts/erpnext-custom-backup.sh

Architecture

Three independent Docker Compose stacks:

  • traefik (traefik-traefik-1): Reverse proxy on ports 80/443, reads container labels from Docker socket to auto-discover routes, issues Let's Encrypt certs. Critical: requires Docker API ≥ 1.40 (Docker ≥ 29.0). Currently pinned to Docker 28.2.2 via apt-mark hold because Traefik v2.11 uses Docker API 1.24.
  • mariadb (mariadb-database): Shared database on mariadb-network. All ERPNext containers connect to this network to reach the DB.
  • erpnext (6+ containers): Runs the ERPNEXT_CUSTOM_IMAGE:ERPNEXT_CUSTOM_TAG image.

Networks:

  • traefik-public: Traefik + ERPNext frontend only. Traefik reads frontend labels to create HTTPS router.
  • mariadb-network: MariaDB + all ERPNext service containers (backend, queues, scheduler, websocket).
  • erpnext-erp-adomio-com: Internal ERPNext container communication.

Important: When traefik-docker.sh down is run, the traefik-public network is destroyed. ERPNext containers lose their Traefik connection and must be restarted (erpnext-custom-docker.sh down && up) to reconnect. Same issue can happen with mariadb-network when MariaDB is restarted.

Configuration Files

  • .env: Master config — contains ERPNEXT_CUSTOM_IMAGE, ERPNEXT_CUSTOM_TAG, backup credentials (Restic/S3), and paths.
  • .configs/traefik.env: Traefik domain, email, hashed admin password (generated by traefik-setup.sh)
  • .configs/mariadb.env: DB password (generated by mariadb-setup.sh)
  • .configs/erpnext.env: ERPNext env vars copied from .frappe_docker/example.env
  • .configs/erpnext-custom-docker-compose.yaml: Generated file — do not edit directly, regenerated by erpnext-custom-setup.sh
  • apps.json: Frappe apps included in the custom image (ERPNext, HRMS, print_designer, erpnext_germany — all version-15)

Custom Image Build

Two-stage build in erpnext-custom-setup.sh:

  1. base:latest — built from .frappe_docker/images/layered/Containerfile with APPS_JSON_BASE64 arg (clones all apps from apps.json)
  2. $ERPNEXT_CUSTOM_IMAGE:$ERPNEXT_CUSTOM_TAG — built from images/layered/Dockerfile (extends base, installs per-app requirements.txt, uses 2-worker gunicorn)

Tag version is controlled by ERPNEXT_CUSTOM_TAG in .env. The generated compose file bakes in the image reference (PULL_POLICY=never), so bump the tag before rebuilding to avoid conflicts.

Deployment Versioning

  1. Update apps.json if app versions changed
  2. Bump ERPNEXT_CUSTOM_TAG in .env
  3. Run scripts/erpnext-custom-setup.sh (builds and regenerates compose file)
  4. Restart + migrate (see Key Commands above)

Backup

Backups are handled entirely by ERPNext's built-in scheduler and backup feature (configured under Settings → Backups in the ERPNext UI). No external scripts or cron jobs are needed.