geniusdynamics/erpnext

Genius Dynamics ERPNext Docker镜像（非洲地区专用）

镜像概述

本Docker镜像专为东非及非洲国家设计，集成了针对这些地区的特定模块，最初开发用于NethServer 8（NS8）的ERPNext模块（https://github.com/geniusdynamics/ns8-erp-next%EF%BC%89%E3%80%82%E8%AF%A5%E9%95%9C%E5%83%8F%E6%8F%90%E4%BE%9B%E5%8F%AF%E5%AE%9A%E5%88%B6%E7%9A%84ERPNext%E9%83%A8%E7%BD%B2%E9%85%8D%E7%BD%AE%EF%BC%8C%E4%BC%98%E5%8C%96%E4%BA%86NS8%E6%A8%A1%E5%9D%97%E7%8E%AF%E5%A2%83%EF%BC%8C%E5%90%8C%E6%97%B6%E4%B9%9F%E9%80%82%E7%94%A8%E4%BA%8E%E9%80%9A%E7%94%A8Docker%E5%9C%BA%E6%99%AF%E3%80%82

核心功能与特性

• 多阶段构建：生成精简的运行时镜像，减少资源占用
• 动态应用安装：通过apps.json配置文件自动安装自定义Frappe应用
• 多站点管理：支持通过环境变量配置和创建多个站点
• NS8兼容入口点：提供生命周期管理支持，符合NS8模块规范
• 自动化构建：通过GitHub Actions实现自动构建和版本标记

环境变量配置

站点创建与管理

• ENABLE_AUTO_SITE（布尔值）：设为true时，容器启动或执行create-site命令时自动创建站点并安装应用，默认false
• SITES（字符串）：逗号分隔的站点名称列表（如site1.localhost,site2.example.com），仅在ENABLE_AUTO_SITE=true时生效
• ADMIN_PASS（字符串）：新创建Frappe站点的管理员密码，默认admin

数据库配置（主要用于common_site_config.json）

以下变量通常由NS8或配置脚本用于填充sites/common_site_config.json，入口点脚本依赖此文件完成站点创建和服务启动：

• DB_HOST：MariaDB/PostgreSQL服务器的主机名或IP地址
• DB_PORT：数据库服务器端口（如MariaDB默认3306）
• DB_USER：Frappe数据库用户（通常由bench创建）
• DB_PASSWORD：Frappe数据库用户密码

Redis配置（主要用于common_site_config.json）

• REDIS_CACHE：缓存用Redis连接字符串（如redis://redis-cache:6379）
• REDIS_QUEUE：后台任务队列用Redis连接字符串（如redis://redis-queue:6379）
• REDIS_SOCKETIO：Socket.IO用Redis连接字符串（通常与REDIS_QUEUE相同）

Frappe/Web服务器配置

• FRAPPE_SITE_NAME_HEADER（字符串）：Nginx/代理用于确定请求站点名称的HTTP头（如$host、X-Frappe-Site-Name），多站点设置必备
• SOCKETIO_PORT（整数）：Frappe Socket.IO服务监听端口（如9000）
• DEBUG_ENTRYPOINT（布尔值）：设为true时，入口点脚本（entrypoint.sh）将启用set -x以输出详细调试日志

自定义应用安装

镜像支持在构建时安装自定义Frappe应用，可通过仓库根目录的apps.json文件或指定URL实现。

1. 使用仓库中的apps.json

在仓库根目录创建apps.json文件，构建过程会自动读取。示例：

json
[
  {
    "url": "https://github.com/frappe/erpnext",
    "branch": "version-15"
  },
  {
    "url": "https://github.com/genforge/navari_csf_ke",
    "branch": "develop"
  },
  {
    "url": "https://github.com/genforge/frappe-mpsa-payments",
    "branch": "develop"
  }
]

注：若省略name字段，将从URL自动提取。确保构建时URL可访问。

2. 使用APPS_JSON_URL构建参数

构建时指定外部apps.json文件URL：

shell
docker build --build-arg APPS_JSON_URL="https://example.com/path/to/apps.json" -t geniusdynamics/erpnext:latest .

3. 使用APPS_JSON_BASE64构建参数（传统方式）

将apps.json内容编码为base64字符串传递：

shell
export APPS_JSON_BASE64=$(base64 -w 0 my_apps.json)
docker build --build-arg APPS_JSON_BASE64=$APPS_JSON_BASE64 -t geniusdynamics/erpnext:latest .

应用安装由scripts/install_apps.sh脚本处理，通过bench get-app命令获取并安装应用。若apps.json格式错误，构建将失败。

入口点与命令（scripts/entrypoint.sh）

镜像使用scripts/entrypoint.sh作为主入口点，行为如下：

默认行为

• 容器启动时检查Frappe实例配置（即sites/common_site_config.json是否包含必要的数据库和Redis信息）
• 未配置：输出提示信息后等待配置（符合NS8规范）
• 已配置：
  • 若ENABLE_AUTO_SITE=true且SITES已定义，通过scripts/create_site.sh创建站点并安装应用
  • 启动Frappe服务（通常为bench start，包含Gunicorn Web服务器和后台工作进程）

手动创建站点

通过docker exec触发站点创建/应用安装：

shell
docker exec <容器名称或ID> create-site

将使用SITES和ADMIN_PASS环境变量。

运行bench命令

执行任意bench命令：

shell
docker exec <容器名称或ID> bench version
docker exec <容器名称或ID> bench backup --with-files
docker exec <容器名称或ID> bench migrate

手动启动服务

配置完成后手动启动服务：

shell
docker exec <容器名称或ID> start
# 或直接启动Gunicorn
docker exec <容器名称或ID> gunicorn

构建镜像

自动构建（GitHub Actions）

仓库配置了GitHub Actions工作流（.github/workflows/autobuild.yml），触发条件：

• main分支推送（针对Dockerfile、脚本、apps.json等相关文件）
• 每日定时任务
• 手动触发

工作流会：

• 获取最新官方ERPNext发布标签
• 构建多平台镜像（linux/amd64、linux/arm64）
• 标记为ERPNext版本（如15.1.0、v15）并推送到Docker Hub（geniusdynamics/erpnext）和/或GitHub Container Registry（ghcr.io/geniusdynamics/erpnext）

手动构建

手动构建命令：

shell
docker build -t geniusdynamics/erpnext:custom .

可通过构建参数自定义：

• FRAPPE_BRANCH：指定初始化bench的Frappe分支（如version-15），默认version-15
• ERPNEXT_VERSION：信息性参数，通常设为目标ERPNext标签，供GitHub Actions使用
• APPS_JSON_URL：外部apps.json文件URL
• APPS_JSON_BASE64：base64编码的apps.json内容

示例：

shell
docker build \
  --build-arg FRAPPE_BRANCH="version-15" \
  --build-arg ERPNEXT_VERSION="v15.10.0" \
  --build-arg APPS_JSON_URL="https://example.com/apps.json" \
  -t geniusdynamics/erpnext:latest .

运行容器

基本docker run示例

需提前准备运行中的MariaDB和Redis：

shell
docker run -d \
  --name my-erpnext-app \
  -p 8000:8000 \
  -e ENABLE_AUTO_SITE=true \
  -e SITES="myerp.localhost" \
  -e ADMIN_PASS="securepassword" \
  -e DB_HOST="your_db_host" \
  -e DB_PORT="3306" \
  -e REDIS_CACHE="redis://your_redis_cache_host:6379" \
  -e REDIS_QUEUE="redis://your_redis_queue_host:6379" \
  -e SOCKETIO_PORT="9000" \
  -e FRAPPE_SITE_NAME_HEADER="myerp.localhost" \
  -v erpnext_sites:/home/frappe/frappe-bench/sites \
  -v erpnext_logs:/home/frappe/frappe-bench/logs \
  geniusdynamics/erpnext:latest

注：完整部署需数据库（MariaDB/PostgreSQL）和Redis实例，仓库中的docker-compose.yml提供完整示例。

Docker Compose示例

仓库包含docker-compose.yml，用于多容器部署（适用于开发和测试），协调ERPNext应用容器与MariaDB、Redis服务。

使用步骤：

1. 安装Docker和Docker Compose
2. 从example.env创建.env文件并自定义变量（如SITES、ADMIN_PASS、MYSQL_ROOT_PASSWORD）：

   shell
   cp example.env .env
   # 编辑.env配置
   

3. 启动服务：

   shell
   docker-compose up -d
   

首次设置（若未使用NS8预配置common_site_config.json）

入口点需要sites/common_site_config.json包含数据库和Redis信息才能创建站点或启动服务。若文件缺失或信息不全，需通过bench set-config设置：

shell
# 等待容器启动后执行
docker-compose exec erpnext bench set-config -g db_host db
docker-compose exec erpnext bench set-config -gp db_port 3306  # 确保为整数
docker-compose exec erpnext bench set-config -g redis_cache redis://redis-cache:6379
docker-compose exec erpnext bench set-config -g redis_queue redis://redis-queue:6379
docker-compose exec erpnext bench set-config -g redis_socketio redis://redis-queue:6379
docker-compose exec erpnext bench set-config -gp socketio_port 9000  # 确保为整数

之后触发站点创建：

shell
docker-compose exec erpnext create-site

或重启服务：

shell
docker-compose restart erpnext

镜像标签

CI工作流推送的镜像标签格式：

• geniusdynamics/erpnext:<version>（如geniusdynamics/erpnext:15.1.0）
• geniusdynamics/erpnext:<major_version>（如geniusdynamics/erpnext:v15）

GitHub Container Registry地址：ghcr.io/geniusdynamics/erpnext