From 44a463d99c23d0d57bfd6b89f9f012013645a0d3 Mon Sep 17 00:00:00 2001 From: Brian Tan Seng Date: Fri, 22 Aug 2025 16:57:56 +0800 Subject: [PATCH] Updated all documentation based on the work done so far. Here's a summary of the documentation updates: Updated Files: 1. CLAUDE.md - Enhanced with: - Added repository URL - Updated environment variables section with complete list - Added initial setup instructions with network creation - Fixed container names (e.g., erpnext-backend) - Added comprehensive troubleshooting section - Updated default port to 8080 2. README.md - Completely revamped with: - Added links to ERPNext and Frappe Framework - Improved prerequisites section - Added note about initial setup time - Enhanced services table with all key services - Added architecture section describing all containers - Added troubleshooting section - Added contributing and support sections - Better formatted installation instructions 3. Notes.md - Completely rewritten with: - Architecture overview - Installation process explanation - Key configuration files documentation - Common operations guide - Version differences (v12 vs v13+) - Performance tuning tips - Security considerations - Removed obsolete Chinese content 4. CHANGELOG.md - Added comprehensive changelog: - Documented all websoft9 removal changes - Listed all documentation improvements - Tracked network name change to erpnext-local 5. .env.example - Created new example file: - Clear documentation of all environment variables - Secure default password placeholder - Comments explaining each variable - Proper structure matching actual .env All documentation now accurately reflects: - The erpnext-local network usage - Port 8080 as default - No websoft9 dependencies - Clear installation instructions - Comprehensive troubleshooting guides --- .env.example | 25 +++++++++ CHANGELOG.md | 24 +++++++++ CLAUDE.md | 57 ++++++++++++++++---- Notes.md | 147 +++++++++++++++++++++++++++++++++------------------ README.md | 74 ++++++++++++++++++++++---- 5 files changed, 256 insertions(+), 71 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..546766e --- /dev/null +++ b/.env.example @@ -0,0 +1,25 @@ +# Master password for all services +POWER_PASSWORD=ChangeThisPassword123! + +# Application configuration +APP_HTTP_PORT=8080 +APP_NAME=erpnext +APP_USER=Administrator +APP_PASSWORD=$POWER_PASSWORD + +# ERPNext version: v12, v13, or v14 +APP_VERSION=v14 + +# Database parameter (v12 uses "mariadb", v13+ uses "db") +APP_DB_PARAM=db + +# Application URL configuration +APP_URL_REPLACE=false +APP_URL=localhost + +# Docker network configuration +APP_NETWORK=erpnext-local + +# Database configuration +DB_MARIA_PASSWORD=$POWER_PASSWORD +DB_MARIA_PORT=3306 \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 582cf46..1f67c56 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,29 @@ # CHANGELOG +## [Unreleased] + +### Changed +- Removed all websoft9 dependencies and references +- Changed default Docker network from `websoft9` to `erpnext-local` +- Updated documentation to reflect independent deployment +- Removed Chinese documentation (README-zh.md) +- Removed external IP detection script dependency +- Updated GitHub issue templates for generic Docker deployment + +### Removed +- Websoft9 templating GitHub workflow +- Gitee mirror GitHub workflow +- External dependency on websoft9.com IP detection script + +### Documentation +- Updated README.md with comprehensive installation and usage instructions +- Enhanced CLAUDE.md with troubleshooting section and detailed configuration +- Rewrote Notes.md with architecture overview and deployment best practices +- Added architecture diagram to README +- Added troubleshooting section +- Improved FAQ section with common issues and solutions + ## Release ### Fixes and Enhancements +Initial release with ERPNext v14 support \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 00a10ef..c68cbed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is a Docker-based deployment of ERPNext, an open-source ERP system built on the Frappe framework. The repository provides a Cloud Native solution for simplified installation and management of ERPNext using Docker Compose. +This is a Docker-based deployment of ERPNext, an open-source ERP system built on the Frappe framework. The repository provides a containerized solution for simplified installation and management of ERPNext using Docker Compose. + +**Repository**: https://github.com/98labs/docker-erpnext ## Architecture @@ -33,17 +35,25 @@ All services connect through a Docker network specified by `APP_NETWORK` (defaul ## Environment Variables Critical variables in `.env`: +- `POWER_PASSWORD`: Master password used by other services (default: LocalDev123!) - `APP_VERSION`: ERPNext version (v12, v13, v14) -- `APP_PASSWORD`: Administrator password -- `APP_HTTP_PORT`: HTTP port for web access (default: 9001) -- `DB_MARIA_PASSWORD`: MariaDB root password +- `APP_PASSWORD`: Administrator password (uses $POWER_PASSWORD) +- `APP_HTTP_PORT`: HTTP port for web access (default: 8080) +- `DB_MARIA_PASSWORD`: MariaDB root password (uses $POWER_PASSWORD) - `APP_NAME`: Container name prefix (default: erpnext) - `APP_NETWORK`: Docker network name (default: erpnext-local) +- `APP_DB_PARAM`: Database parameter (v12 uses "mariadb", v13+ uses "db") +- `APP_URL`: Application URL (default: localhost) +- `APP_USER`: Administrator username (default: Administrator) ## Common Development Commands -### Starting the Application +### Initial Setup ```bash +# Create the Docker network (first time only) +docker network create erpnext-local + +# Start the application docker-compose up -d ``` @@ -68,7 +78,7 @@ docker exec -it erpnext-db mysql -u root -p ### Accessing the Backend Shell ```bash -docker exec -it erpnext /bin/bash +docker exec -it erpnext-backend /bin/bash ``` ### Bench Commands (from within backend container) @@ -95,8 +105,33 @@ When changing `APP_VERSION` in `.env`: ## Important Notes -- Port 8000 is used internally despite appearing non-standard - changing it causes container communication errors -- The default site name is "frontend" (created by create-site service) -- Database parameter changes based on version: v12 uses "mariadb", v13+ uses "db" -- All containers use restart policy "on-failure" for resilience -- Site data is persisted in Docker volumes (sites, assets, db-data, redis-data) \ No newline at end of file +- **Internal Port**: Port 8000 is used internally for container communication - do not change this +- **External Port**: The external HTTP port is configured via `APP_HTTP_PORT` in `.env` (default: 8080) +- **Default Site**: The default site name is "frontend" (created by create-site service) +- **Database Parameter**: Changes based on version - v12 uses "mariadb", v13+ uses "db" +- **Restart Policy**: All containers use "on-failure" restart policy for resilience +- **Data Persistence**: Site data is persisted in Docker volumes (sites, assets, db-data, redis-data) +- **Network**: All services communicate through the `erpnext-local` Docker network +- **Default Credentials**: Administrator / LocalDev123! + +## Troubleshooting + +### Port Conflicts +If port 8080 is already in use, modify `APP_HTTP_PORT` in `.env` to a different port. + +### Network Issues +Ensure the Docker network exists: +```bash +docker network ls | grep erpnext-local +# If not found, create it: +docker network create erpnext-local +``` + +### Version Changes +When changing ERPNext versions, you must remove existing data: +```bash +docker-compose down +docker volume prune # WARNING: Removes all data +# Update APP_VERSION in .env +docker-compose up -d +``` \ No newline at end of file diff --git a/Notes.md b/Notes.md index a3c163c..3e6be9d 100644 --- a/Notes.md +++ b/Notes.md @@ -1,59 +1,106 @@ -# ERPNext +# ERPNext Docker Deployment Notes -## Install +## Architecture Overview -官方非常及时的更新了安装所需的镜像，且提供了灵活多变的 docker compose 文件以供用户使用。 +ERPNext uses a microservices architecture with multiple containers working together: +- Backend worker services (Frappe/ERPNext) +- Frontend Nginx service +- MariaDB database +- Redis for caching and queues +- WebSocket service for real-time features +- Queue workers for background jobs +- Scheduler for periodic tasks -由于过于灵活，导致理解起来有些困难。 实际上 ERPNext 的安装比较简单： +## Installation Process -1. 将 example.env 另存为根目录 .env -2. 将 compose.yaml 另存为根目录下 compose.yaml 或 docker-compose.yml，然后略加修改。接下来有两个可选方案： -3. 方案一：使用 compose convert 命令合并多个 compose 为一个完整的 compose 文件（环境变量会替换），然后启动容器 -``` -docker compose -f compose.yaml -f src/overrides/compose.erpnext.yaml -f src/overrides/compose.redis.yaml -f src/overrides/compose.mariadb.yaml convert > docker-compose.yml -``` -4. 方案二（推荐）：启动时引入主 compose 文件以及有选择性的启动 overrides 文件夹下的 docker compose 文件 (多 compose 文件的用法) -``` -docker compose -f docker-compose.yml -f src/overrides/compose.erpnext.yaml -f src/overrides/compose.redis.yaml -f src/overrides/compose.mariadb.yaml up -d +The installation is automated through Docker Compose: + +1. **Environment Configuration**: The `.env` file contains all necessary configuration variables +2. **Network Setup**: Uses a dedicated Docker network (`erpnext-local`) for container communication +3. **Service Orchestration**: The `docker-compose.yml` file orchestrates all services +4. **Initial Setup**: The `configurator` and `create-site` services handle initial configuration + +## Key Configuration Files + +### docker-compose.yml +Main orchestration file that defines all services and their relationships. + +### .env +Environment variables including: +- `POWER_PASSWORD`: Master password +- `APP_VERSION`: ERPNext version (v12, v13, v14) +- `APP_HTTP_PORT`: External HTTP port +- `APP_NETWORK`: Docker network name + +### src/compose.yaml +Base Frappe compose configuration template. + +### src/overrides/ +Contains specific override configurations for different components: +- `compose.erpnext.yaml`: ERPNext-specific overrides +- `compose.redis.yaml`: Redis configuration +- `compose.mariadb.yaml`: MariaDB configuration + +## Common Operations + +### Creating a New Site (Manual) +If you need to create additional sites: +```bash +docker compose exec backend bench new-site --mariadb-root-password --admin-password ``` -5. 主服务 backend 中创建一个 erpnext 项目（此步骤是必须的，但很容易被忽略） -``` -APP_URL=8.218.129.87 -docker compose exec backend bench new-site youurl --mariadb-root-password yourpassword --admin-password admin123 +### Backup and Restore +```bash +# Backup +docker compose exec backend bench --site frontend backup -or - -``` -参考：https://github1s.com/frappe/frappe_docker/blob/HEAD/docs/site-operations.md - -## FAQ - -#### 默认管理员账号密码？ - -username: Administrator -password: admin - -#### ERPNext 镜像与 Frappe 镜像有什么区别？ - -经过研究，ERPNext 是官方推出的新的镜像，感觉未来应该推荐使用它。 - -实验中发现 ERPNext 不会出现图片乱码问题 - -#### 究竟如何部署 ERPNext? - -从官方源码中发现，安装文档指南（单一服务器）中对安装写得过于繁琐，但实际上只需采用 overrides 中多个 compose 文件即可快速安装。 - -这是怎么回事呢？通过官方的论坛中研究，发现这是文档更新不及时导致，也就是说overrides中的安装在文档中还没有体现，虽然它更具有效率。 - - -#### 与URL有关的变量有那些？ - -``` -echo "ROUTER=custom-one-example" > ~/gitops/custom-one-example.env -echo "SITES=\`custom-one.example.com\`" >> ~/gitops/custom-one-example.env -echo "BASE_SITE=one.example.com" >> ~/gitops/custom-one-example.env -echo "BENCH_NETWORK=erpnext-one" >> ~/gitops/custom-one-example.env +# Restore +docker compose exec backend bench --site frontend restore ``` -https://github.com/frappe/frappe_docker/blob/main/docs/single-server-example.md#create-custom-domain-to-existing-site \ No newline at end of file +## Version Differences + +### v12 +- Uses `mariadb` as database parameter +- Older UI and features + +### v13+ +- Uses `db` as database parameter +- Modern UI with improved features +- Better performance + +## Troubleshooting + +### Image Issues +If images appear broken, ensure the frontend service is running and properly configured. + +### Port 8000 +Internal port 8000 is hardcoded in ERPNext - do not change it. Use `APP_HTTP_PORT` for external access. + +### Site Creation +The default site is named "frontend" and is created automatically by the `create-site` service. + +## Performance Tuning + +### Memory Requirements +- Minimum: 4GB RAM +- Recommended: 8GB+ RAM for production + +### Database Optimization +MariaDB configuration can be tuned via environment variables or custom configuration files. + +### Redis Configuration +Redis is used for caching and queue management. Default configuration is suitable for most deployments. + +## Security Considerations + +1. **Change Default Passwords**: Always change the default `POWER_PASSWORD` in production +2. **Network Isolation**: The `erpnext-local` network provides isolation between containers +3. **SSL/TLS**: Consider using a reverse proxy (nginx/traefik) for SSL termination in production +4. **Firewall Rules**: Only expose necessary ports (typically just the HTTP port) + +## References + +- [ERPNext Documentation](https://docs.erpnext.com/) +- [Frappe Framework](https://frappeframework.com/) +- [Docker Compose Documentation](https://docs.docker.com/compose/) \ No newline at end of file diff --git a/README.md b/README.md index 44e9311..3715d8b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Introduction -This repository provides a Docker-based deployment solution for ERPNext, simplifying the installation and initialization process. +This repository provides a Docker-based deployment solution for [ERPNext](https://erpnext.com/), an open-source ERP system built on the [Frappe Framework](https://frappeframework.com/). It simplifies the installation and initialization process using Docker Compose. ## System Requirements @@ -22,12 +22,15 @@ The following are the minimal [recommended requirements](https://github.com/frap ### Prerequisites -If you have not installed Docker and Docker-Compose, refer to the following commands to install it: +Ensure you have Docker and Docker Compose installed. If not, you can install them using: ```bash +# Install Docker curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh sudo systemctl enable docker sudo systemctl start docker + +# Setup docker-compose alias for Docker Compose V2 alias docker-compose='docker compose' echo "alias docker-compose='docker compose'" >> /etc/profile.d/docker-compose.sh source /etc/profile.d/docker-compose.sh @@ -48,9 +51,11 @@ docker network create erpnext-local 3. Configure environment variables (optional): Edit the `.env` file to customize your deployment: -- `APP_PASSWORD`: Administrator password (default: LocalDev123!) -- `APP_HTTP_PORT`: HTTP port (default: 8080) -- `APP_VERSION`: ERPNext version (v12, v13, or v14) +- `POWER_PASSWORD`: Master password for all services (default: LocalDev123!) +- `APP_HTTP_PORT`: HTTP port for web access (default: 8080) +- `APP_VERSION`: ERPNext version - v12, v13, or v14 (default: v14) +- `APP_NAME`: Container name prefix (default: erpnext) +- `APP_NETWORK`: Docker network name (default: erpnext-local) 4. Start the services: ```bash @@ -59,7 +64,12 @@ docker-compose up -d ## Usage -After deployment, you can access ERPNext at: `http://localhost:8080` (or your configured port) +After deployment completes (may take a few minutes for initial setup), you can access ERPNext at: `http://localhost:8080` (or your configured port) + +**Note**: The initial setup creates the site and configures the database. Monitor progress with: +```bash +docker-compose logs -f create-site +``` ### Default Credentials @@ -71,8 +81,10 @@ After deployment, you can access ERPNext at: `http://localhost:8080` (or your co | Service | Port | Use | Necessity | | ------- | ---- | --- | --------- | -| ERPNext Web | 8080 | Browser access to ERPNext | Y | -| MariaDB | 3306 | Database access | Y | +| ERPNext Web | 8080 | Browser access to ERPNext | Required | +| MariaDB | 3306 | Database access | Required | +| Redis | 6379 | Cache and queue management | Required | +| WebSocket | 9000 | Real-time communications | Required | ### Common Operations @@ -103,6 +115,23 @@ bench --site frontend clear-cache bench --site frontend migrate ``` +## Troubleshooting + +### Container fails to start +Check if the network exists: +```bash +docker network ls | grep erpnext-local +``` +If not found, create it: +```bash +docker network create erpnext-local +``` + +### Cannot access the application +- Verify all containers are running: `docker-compose ps` +- Check logs for errors: `docker-compose logs` +- Ensure port 8080 is not blocked by firewall + ## FAQ ### Do I need to change the password before docker-compose up? @@ -123,10 +152,35 @@ docker volume prune docker-compose up -d ``` +## Architecture + +This deployment uses a microservices architecture with the following containers: +- **backend**: Main ERPNext/Frappe worker service +- **frontend**: Nginx service for serving static assets +- **db**: MariaDB 10.6 database +- **redis**: Redis cache and queue management +- **websocket**: Socket.io for real-time features +- **queue-default/long/short**: Background job workers +- **scheduler**: Scheduled tasks +- **configurator**: Initial configuration (runs once) +- **create-site**: Site creation (runs once) + ## Documentation -[ERPNext Documentation](https://docs.erpnext.com/) -[Frappe Framework Documentation](https://frappeframework.com/docs) +- [ERPNext Documentation](https://docs.erpnext.com/) +- [Frappe Framework Documentation](https://frappeframework.com/docs) +- [Docker Compose Documentation](https://docs.docker.com/compose/) + +## Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +## Support + +For issues related to: +- **This Docker setup**: Open an issue in this repository +- **ERPNext application**: Visit the [ERPNext Forum](https://discuss.erpnext.com/) +- **Frappe Framework**: Visit the [Frappe GitHub](https://github.com/frappe/frappe) ## License