bench get-app https://github.com/dieuluucanh/kiwifood-erp

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=dieuluucanh%2Fkiwifood-erp)](https://frappegems.com/gems/apps/dieuluucanh/kiwifood-erp)

Kiwifood ERP

Kiwifood's distribution platform built on top of ERPNext — never by forking it. This repository is a standard Frappe app (installable via bench get-app) that also carries its own deployment configuration under deploy/.

Environments: dev bench (below) → local staging (docs/LOCAL.md) → staging/production VPS (docs/DEPLOYMENT.md).

Stack

Layer	Source	Pinned where
Frappe framework	frappe/frappe@version-16	deploy/apps.json
ERPNext	frappe/erpnext@version-16	deploy/apps.json
Kiwifood customizations	this repo	—
Docker images & compose	frappe/frappe_docker	pinned via FRAPPE_DOCKER_REF in build-deploy.yml (currently v3.2.2)

Repository layout

kiwifood_erp/
├── kiwifood_erp/            the Frappe app package (bench-compatible at repo root)
│   ├── hooks.py             extension points: doc_events, fixtures, overrides
│   ├── install.py           after_install hook
│   ├── modules.txt          module: Kiwifood
│   └── ...
├── deploy/
│   ├── apps.json            app pins used to build production images
│   └── env/custom.env.example  template for VPS .env (copy → custom.env, fill secrets)
├── docs/
│   ├── LOCAL.md             run the real release image locally (WSL2 + Docker Desktop)
│   ├── DEPLOYMENT.md        one-time runbook: GitHub settings → VPS bootstrap → verification
│   └── UPGRADES.md          upgrade playbook (routine refresh → major version) + rollback
├── .github/workflows/
│   ├── ci.yml               lint + server tests against real frappe+erpnext
│   └── build-deploy.yml     build image → GHCR → deploy staging/prod over SSH
└── pyproject.toml           packaging + ruff config

Local development (Docker-based)

git clone https://github.com/frappe/frappe_docker ~/frappe_docker
cd ~/frappe_docker/development
cp example/env-example .env                      # then follow frappe_docker dev docs
docker compose up -d                              # mariadb + redis services

# one-time bench bootstrap inside container:
docker compose exec backend bash
  bench init --frappe-branch version-16 ~/frappe-bench
  cd ~/frappe-bench
  bench get-app erpnext --branch version-16 https://github.com/frappe/erpnext
  bench get-app kiwifood_erp /workspace           # mount this repo into container
  bench new-site dev.local --install-app erpnext --install-app kiwifood_erp --admin-password admin
  bench start

Daily loop: edit code in this repo → hot reload on :8000 → bench --site dev.local migrate after DocType changes → bench --site dev.local run-tests --app kiwifood_erp.

To test built releases (not hot-reload code) on this machine, use docs/LOCAL.md instead.

Customization discipline

All changes go through this app:

• New DocTypes/pages/APIs → normal app code (kiwifood_erp//)
• Fields added to ERPNext DocTypes → Custom Fields exported as fixtures/custom_doctype_fields.json (bench --site ... export-fixtures), declared in hooks.py::fixtures
• Reacting to ERPNext events → doc_events in hooks.py
• Method overrides → override_whitelisted_methods / hooks patterns
• ❌ Never commit edits to erpnext or frappe source; urgent upstream fixes are hooked here and upstreamed via PR.

CI/CD

• PRs: ruff lint + full bench test job (installs frappe v16 + erpnext v16 + this app, runs tests)
• merge to main: builds layered image with frappe_docker/images/layered/Containerfile, pushes ghcr.io/dieuluucanh/kiwifood-platform (tags: latest, sha-), deploys staging (deploy script runs bench --site all migrate after recreating containers)
• tag vX.Y.Z: same image promoted to production (GitHub environment approval gate)

Required GitHub secrets:

Secret	Purpose
VPS_HOST, VPS_USER, VPS_SSH_KEY	staging SSH
VPS_HOST_PROD, VPS_USER, VPS_SSH_KEY	production SSH

apps.json is read directly from the committed deploy/apps.json — no secret needed (all three repos are public; add a PAT secret only if this repo ever goes private).

VPS setup (one-time)

Full step-by-step runbook: docs/DEPLOYMENT.md — covers GitHub environments/secrets, SSH deploy keys, GHCR private package, VPS compose bootstrap, first site creation, and off-site backups.

Short version:

# on VPS as deploy user, in /opt/kiwifood/production
git clone --depth 1 --branch v3.2.2 https://github.com/frappe/frappe_docker
cp frappe_docker/compose.yaml .
cp frappe_docker/overrides/compose.{mariadb,redis,https,backup-cron}.yaml .
cp /path/to/custom.env .env      # from deploy/env/custom.env.example
docker compose pull backend && docker compose up -d
docker compose exec backend bench new-site  \
    --install-app erpnext --install-app kiwifood_erp --admin-password ''

Subsequent deployments are automated (workflow updates CUSTOM_TAG in .env, pulls the image, recreates containers, runs bench migrate).

Off-site backups are mandatory: the backup-cron volume alone dies with the VPS. See docs/DEPLOYMENT.md §D6.

Upgrades

See the full playbook: docs/UPGRADES.md.

• Routine (staying on v16): floating version-16 branches mean every build absorbs latest upstream fixes — trigger a build (empty commit), smoke-test staging, tag vX.Y.Z → production with approval
• Major (v16→v17): upgrade branch, bump all pins together (apps.json, FRAPPE_BRANCH, FRAPPE_DOCKER_REF, Python floor), test migration on a staging copy of production data first
• Rollback: revert CUSTOM_TAG to previous sha-*; migrations are one-way, so a forward-migrated DB requires backup restore