epistemophiliac/frappe_docker
1
0
Fork 0
mirror of https://github.com/frappe/frappe_docker.git synced 2026-06-24 08:45:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

feat(custom-setup): add custom Docker setup with ERPNext and HRMS

Browse source 
- Add CLAUDE.md with repository guidance for Claude Code
- Add apps.json defining ERPNext and HRMS apps
- Add build-custom-image.sh script for building custom images
- Add docs/README-CUSTOM-SETUP.md with setup instructions
- Update pwd.yml to use custom image and install HRMS app

This enables a complete custom deployment with ERPNext (full ERP) and HRMS (HR management) using Docker containers.
This commit is contained in:
Aneesh 2025-11-16 09:23:42 -06:00
parent 1a799ee4da
commit d3c8cd3638
5 changed files with 577 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

330
CLAUDE.md Normal file
View file

@ -0,0 +1,330 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
This repository provides Docker containerization for Frappe Framework and ERPNext. It supports both development environments and production deployments through multiple compose configurations and image types.
## Repository Architecture
### Multi-Image Strategy
There are **four distinct Dockerfile types** in `images/`:
- **bench** (`images/bench/Dockerfile`): CLI-only setup for development/debugging
- **custom** (`images/custom/Containerfile`): Production-ready, built from Python base, uses `apps.json` for app installation
- **layered** (`images/layered/Containerfile`): Same as custom but based on prebuilt Docker Hub images for faster builds
- **production** (`images/production/Containerfile`): Quick-start image with only Frappe + ERPNext (not customizable)
**Key principle**: `custom` and `layered` are for real deployments; `production` is for exploration only.
### Multi-Service Architecture
The base `compose.yaml` defines these core services:
- **configurator**: Runs once on startup to configure `common_site_config.json` with database and Redis connection details, then exits
- **backend**: Werkzeug development server (Python) serving dynamic content
- **frontend**: Nginx reverse proxy serving static assets and routing requests
- **websocket**: Node.js Socket.IO server for real-time features
- **queue-short/queue-long**: Python RQ workers for background job processing
- **scheduler**: Python service running scheduled tasks
**Additional services** come from compose overrides in `overrides/`:
- `compose.mariadb.yaml` / `compose.postgres.yaml`: Database services
- `compose.redis.yaml`: Redis cache and queue services
- `compose.proxy.yaml`: Traefik reverse proxy for multi-site hosting
- `compose.https.yaml`: SSL/TLS certificate management
- `compose.noproxy.yaml`: Direct port exposure (no proxy) for development
### Compose File Composition Pattern
The architecture uses Docker Compose overrides to build complete environments:
```bash
docker compose \
-f compose.yaml \
-f overrides/compose.mariadb.yaml \
-f overrides/compose.redis.yaml \
-f overrides/compose.noproxy.yaml \
config > compose.custom.yaml
```
This pattern allows mixing and matching services based on deployment needs.
## Common Development Commands
### Quick Testing Setup (pwd.yml)
For rapid evaluation without local setup:
```bash
# Start all services (uses frappe-custom:v15 image)
docker compose -f pwd.yml up -d
# Monitor site creation (takes ~5 minutes)
docker compose -f pwd.yml logs -f create-site
# Access at http://localhost:8080
# Login: Administrator / admin
```
The `pwd.yml` file is a self-contained configuration that includes all services (MariaDB, Redis, workers, etc.) and automatically creates a site named "frontend".
### Development Environment Setup
Full development with hot-reload:
```bash
# 1. Copy devcontainer configuration
cp -R devcontainer-example .devcontainer
# 2. Open in VSCode with Dev Containers extension
# VSCode will detect .devcontainer and prompt to reopen in container
# 3. Inside container, run automated installer
cd /workspace/development
python installer.py
# Installer arguments:
# -j, --apps-json: Path to apps.json (default: apps-example.json)
# -b, --bench-name: Bench directory name (default: frappe-bench)
# -s, --site-name: Site name, must end with .localhost (default: development.localhost)
# -t, --frappe-branch: Frappe branch (default: version-15)
# -d, --db-type: Database type (mariadb or postgres)
# -a, --admin-password: Admin password (default: admin)
```
Development files are located in `development/frappe-bench/` (git-ignored directory).
### Bench Commands (Inside Container)
```bash
# Site management
bench new-site --mariadb-user-host-login-scope=% <site-name>
bench list-sites
bench --site <site-name> migrate
# App management
bench get-app --branch <branch> <git-url>
bench --site <site-name> install-app <app-name>
bench list-apps
# Development
bench start # Start dev server with hot-reload
bench build # Build frontend assets
bench build --app <app-name> # Build specific app
# Database
bench mariadb # Open MariaDB console
bench --site <site-name> backup --with-files
# Debugging
bench --site <site-name> console # Python REPL with Frappe context
```
## Building Custom Images
### Creating apps.json
Define custom apps to install in `apps.json`:
```json
[
{
"url": "https://github.com/frappe/erpnext",
"branch": "version-15"
},
{
"url": "https://github.com/frappe/hrms",
"branch": "version-15"
}
]
```
### Build Process
```bash
# 1. Encode apps.json
export APPS_JSON_BASE64=$(base64 -w 0 apps.json)
# 2. Build image (example using layered)
docker build \
--build-arg=FRAPPE_PATH=https://github.com/frappe/frappe \
--build-arg=FRAPPE_BRANCH=version-15 \
--build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
--tag=custom:15 \
--file=images/layered/Containerfile .
# Or use docker-bake.hcl for multi-arch builds
docker buildx bake --no-cache
```
**Important build args**:
- `FRAPPE_PATH`: Frappe framework repo URL
- `FRAPPE_BRANCH`: Frappe framework branch
- `APPS_JSON_BASE64`: Base64-encoded apps.json
- `PYTHON_VERSION`: Python version (default: 3.11.6)
- `NODE_VERSION`: Node.js version (default: 20.19.2)
## Testing and CI
### Linting
```bash
# Install pre-commit
pip install pre-commit
# or
brew install pre-commit
# Setup hooks
pre-commit install
# Run on all files
pre-commit run --all-files
```
### Integration Tests
```bash
# Setup test environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-test.txt
# Run tests
pytest
```
## Site Operations
### Creating a New Site
```bash
# Basic site creation
docker compose exec backend \
bench new-site --mariadb-user-host-login-scope=% \
--db-root-password <db-password> \
--admin-password <admin-password> <site-name>
# For PostgreSQL
docker compose exec backend bench set-config -g root_login postgres
docker compose exec backend bench set-config -g root_password <password>
docker compose exec backend \
bench new-site --db-type postgres \
--admin-password <admin-password> <site-name>
```
**Note**: The `--mariadb-user-host-login-scope=%` option is critical for Docker networking - it allows database users to connect from any host (%).
### Accessing Container Files
```bash
# Enter backend container
docker compose exec backend bash
# Key directories inside container:
# /home/frappe/frappe-bench/apps/ - All Frappe applications
# /home/frappe/frappe-bench/sites/ - Site data and configuration
# /home/frappe/frappe-bench/logs/ - Application logs
# Copy files from container to host
docker compose cp backend:/home/frappe/frappe-bench/apps/my_app ./local-apps/
```
## Environment Variables
The main environment variables (from `example.env`):
- `ERPNEXT_VERSION`: Version tag for ERPNext image
- `DB_HOST`, `DB_PORT`: External database connection (if not using compose.mariadb.yaml)
- `REDIS_CACHE`, `REDIS_QUEUE`: External Redis connection (if not using compose.redis.yaml)
- `FRAPPE_SITE_NAME_HEADER`: Override site resolution (default: `$$host`)
- `HTTP_PUBLISH_PORT`: HTTP port to publish (default: 8080)
- `LETSENCRYPT_EMAIL`: Email for Let's Encrypt certificates
- `SITES`: Comma-separated list of sites for SSL certificates
See `docs/container-setup/env-variables.md` for complete reference.
## Key Implementation Details
### Service Startup Dependencies
The `configurator` service MUST complete successfully before other services start. It writes database and Redis connection details to `sites/common_site_config.json`. The compose file uses:
```yaml
x-depends-on-configurator: &depends_on_configurator
depends_on:
configurator:
condition: service_completed_successfully
```
### Nginx Configuration
The `frontend` service uses `nginx-entrypoint.sh` which dynamically generates Nginx configuration from `resources/nginx-template.conf` using environment variables like `BACKEND`, `SOCKETIO`, `FRAPPE_SITE_NAME_HEADER`.
### Volume Mounts
- **sites**: Shared across all services, contains site data and configuration
- **logs**: Application logs (optional, for debugging)
For development, bind mount `./development/frappe-bench` to `/workspace/development` in the container.
## Platform-Specific Notes
### ARM64 / Apple Silicon
```bash
# Build multi-arch images
docker buildx bake --no-cache --set "*.platform=linux/arm64"
# For pwd.yml on ARM64
# 1. Add platform: linux/arm64 to all services
# 2. Replace version tags with :latest
```
Use `:cached` or `:delegated` volume flags on macOS for better performance.
## Project Structure Reference
```
frappe_docker/
├── compose.yaml # Base compose file (core services)
├── pwd.yml # Self-contained quick-start config
├── docker-bake.hcl # Buildx bake configuration
├── example.env # Environment variables template
├── images/ # Dockerfile definitions
│ ├── bench/ # CLI-only image
│ ├── custom/ # Production image (apps.json)
│ ├── layered/ # Fast-build production image
│ └── production/ # Quick-start image (Frappe + ERPNext only)
├── overrides/ # Compose file extensions
│ ├── compose.mariadb.yaml
│ ├── compose.redis.yaml
│ ├── compose.proxy.yaml
│ └── compose.https.yaml
├── resources/ # Runtime templates
│ ├── nginx-entrypoint.sh
│ └── nginx-template.conf
├── development/ # Dev environment (git-ignored)
│ └── installer.py # Automated setup script
├── devcontainer-example/ # VSCode devcontainer template
└── docs/ # Documentation
```
## Version Compatibility
- **Frappe v14**: Python 3.10.13, Node v16
- **Frappe v15**: Python 3.11.6, Node v20 (default)
- **Frappe v13**: Python 3.9.17, Node v14
When working with different versions, set `PYENV_VERSION` and use `nvm` to switch Node versions inside the container.
## Important Development Notes
1. **Site names must end with `.localhost`** for local development
2. **Default MariaDB root password is `123`** in development
3. **Default admin password is `admin`** when using installer.py
4. **Wait for configurator to exit** before creating sites or running migrations
5. **The `development/` directory is git-ignored** - all local development happens here
6. **Use `--mariadb-user-host-login-scope=%`** when creating sites in Docker to enable proper networking

11
apps.json Normal file
View file

@ -0,0 +1,11 @@
[
{
"url": "https://github.com/frappe/erpnext",
"branch": "version-15"
},
{
"url": "https://github.com/frappe/hrms",
"branch": "version-15"
}
]

47
build-custom-image.sh Executable file
View file

@ -0,0 +1,47 @@
#!/bin/bash
# Build custom Frappe Docker image with ERPNext and HRMS
# This script builds a custom image using the apps.json file
set -e
echo "Building custom Frappe image with ERPNext and HRMS..."
# Check if apps.json exists
if [ ! -f "apps.json" ]; then
echo "Error: apps.json file not found!"
exit 1
fi
# Encode apps.json to base64
if [[ "$OSTYPE" == "darwin"* ]]; then
# macOS
APPS_JSON_BASE64=$(base64 -i apps.json)
else
# Linux
APPS_JSON_BASE64=$(base64 -w 0 apps.json)
fi
echo "Building image for AMD64 architecture (for Windows Server deployment)..."
echo "This may take 15-30 minutes depending on your system..."
# Build the image using layered Containerfile
docker build \
--build-arg=FRAPPE_PATH=https://github.com/frappe/frappe \
--build-arg=FRAPPE_BRANCH=version-15 \
--build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
--platform=linux/amd64 \
--tag=frappe-custom:v15 \
--file=images/layered/Containerfile .
echo ""
echo "✅ Build complete!"
echo "Image tagged as: frappe-custom:v15"
echo ""
echo "Next steps:"
echo "1. Run: docker compose -f pwd.yml up -d"
echo "2. Wait for all services to start (2-3 minutes)"
echo "3. Access ERPNext at: http://localhost:8080"
echo " Username: Administrator"
echo " Password: admin"

162
docs/README-CUSTOM-SETUP.md Normal file
View file

@ -0,0 +1,162 @@
# Custom Frappe Setup with ERPNext and HRMS
This setup includes a custom Docker image with two officially supported Frappe applications:
- **ERPNext** - Complete ERP solution (includes built-in CRM, Sales, Accounting, Inventory, and more)
- **HRMS** - Human Resource Management System
## Prerequisites
- Docker Desktop (for Mac/Windows) or Docker Engine (for Linux)
- At least 4GB of free RAM
- 10GB of free disk space
## Quick Start
### Step 1: Build the Custom Image
Run the build script to create a custom Docker image with all three apps:
```bash
./build-custom-image.sh
```
**Note:** This will take 15-30 minutes depending on your system. The script will:
- Read the `apps.json` file containing ERPNext and HRMS
- Build a custom Docker image tagged as `frappe-custom:v15`
- Configure it for ARM64 architecture (Apple Silicon)
### Step 2: Start the Services
Once the build is complete, start all services:
```bash
docker compose -f pwd.yml up -d
```
### Step 3: Wait for Initialization
The first startup takes 2-3 minutes as it:
- Initializes the database
- Creates a new site called "frontend"
- Installs ERPNext and HRMS apps
You can monitor the progress with:
```bash
docker compose -f pwd.yml logs -f create-site
```
Wait until you see a message indicating the site has been created successfully.
### Step 4: Access the System
Once ready, access the system at:
**URL:** http://localhost:8080
**Login Credentials:**
- Username: `Administrator`
- Password: `admin`
## What's Included
### ERPNext
Full-featured ERP with modules for:
- **CRM** - Lead Management, Opportunities, Sales Pipeline
- **Sales & Purchase** - Quotations, Orders, Invoices
- **Accounting** - General Ledger, Accounts Payable/Receivable, Financial Reports
- **Inventory Management** - Stock, Warehouses, Serial/Batch Numbers
- **Manufacturing** - BOM, Work Orders, Production Planning
- **Projects** - Project Management, Tasks, Timesheets
- **Assets** - Asset Management, Maintenance
- And much more...
### HRMS
Human Resource Management with:
- **Employee Management** - Employee Records, Organizational Chart
- **Attendance & Leave** - Attendance Tracking, Leave Management
- **Payroll** - Salary Structure, Payroll Processing
- **Recruitment** - Job Openings, Job Applications
- **Performance Management** - Appraisals, Goals
- **Expense Claims** - Employee Advances, Expense Claims
## Managing the Setup
### Stop Services
```bash
docker compose -f pwd.yml down
```
### View Logs
```bash
# All services
docker compose -f pwd.yml logs -f
# Specific service
docker compose -f pwd.yml logs -f backend
```
### Restart Services
```bash
docker compose -f pwd.yml restart
```
### Remove Everything (including data)
```bash
docker compose -f pwd.yml down -v
```
## Troubleshooting
### Build Fails
- Ensure you have a stable internet connection
- Check that Docker has enough resources allocated (4GB+ RAM)
- Try running the build script again
### Services Won't Start
- Check if ports 8080 is already in use: `lsof -i :8080`
- Ensure Docker is running: `docker ps`
- Check logs: `docker compose -f pwd.yml logs`
### Can't Access at localhost:8080
- Wait 2-3 minutes after starting services
- Check if the create-site service completed: `docker compose -f pwd.yml ps`
- Verify the frontend service is running: `docker compose -f pwd.yml logs frontend`
## Architecture Notes
This setup uses:
- **MariaDB 10.6** for the database
- **Redis** for caching and job queues
- **Nginx** as the web server
- **Node.js** for real-time websockets
- **Python** for the backend application
All services run in separate containers and communicate over a Docker network.
## Customization
To add or remove apps, edit the `apps.json` file and rebuild:
```bash
# Edit apps.json to add more Frappe apps
nano apps.json
# Rebuild the image
./build-custom-image.sh
# Restart services
docker compose -f pwd.yml down
docker compose -f pwd.yml up -d
```
**Note:** ERPNext already includes comprehensive CRM functionality. If you need a standalone modern CRM, consider using Frappe CRM separately instead of with ERPNext to avoid feature overlap.
## Support
For issues specific to:
- **Frappe Framework:** https://github.com/frappe/frappe
- **ERPNext:** https://github.com/frappe/erpnext
- **HRMS:** https://github.com/frappe/hrms
- **Docker Setup:** https://github.com/frappe/frappe_docker

36
pwd.yml
View file

@ -2,7 +2,9 @@ version: "3"
services:
backend:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -18,7 +20,9 @@ services:
MARIADB_ROOT_PASSWORD: admin
configurator:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -47,7 +51,9 @@ services:
- logs:/home/frappe/frappe-bench/logs
create-site:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -77,10 +83,11 @@ services:
fi
done;
echo "sites/common_site_config.json found";
bench new-site --mariadb-user-host-login-scope='%' --admin-password=admin --db-root-username=root --db-root-password=admin --install-app erpnext --set-default frontend;
bench new-site --mariadb-user-host-login-scope='%' --admin-password=admin --db-root-username=root --db-root-password=admin --install-app erpnext --install-app hrms --set-default frontend;
db:
image: mariadb:10.6
platform: linux/amd64
networks:
- frappe_network
healthcheck:
@ -102,7 +109,9 @@ services:
- db-data:/var/lib/mysql
frontend:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
depends_on:
@ -128,7 +137,9 @@ services:
- "8080:8080"
queue-long:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -147,7 +158,9 @@ services:
FRAPPE_REDIS_QUEUE: redis://redis-queue:6379
queue-short:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -167,6 +180,7 @@ services:
redis-queue:
image: redis:6.2-alpine
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -184,7 +198,9 @@ services:
condition: on-failure
scheduler:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy:
@ -198,7 +214,9 @@ services:
- logs:/home/frappe/frappe-bench/logs
websocket:
image: frappe/erpnext:v15.88.1
image: frappe-custom:v15
pull_policy: never
platform: linux/amd64
networks:
- frappe_network
deploy: