Andrey/docker-erpnext
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated all documentation based on the work done so far. Here's a summary of the

Browse Source 
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
This commit is contained in:
Brian Tan Seng 2025-08-22 16:57:56 +08:00
parent 831d1adfe3
commit 44a463d99c
5 changed files with 256 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
.env.example Normal file
View File

@ -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

24
CHANGELOG.md
View File

@ -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

57
CLAUDE.md
View File

@ -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)
- **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
```

147
Notes.md
View File

@ -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 <site-name> --mariadb-root-password <password> --admin-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 <backup-file>
```
https://github.com/frappe/frappe_docker/blob/main/docs/single-server-example.md#create-custom-domain-to-existing-site
## 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/)

74
README.md
View File

@ -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