frappe_docker/HYBRID_DEPLOYMENT.md

Hybrid Deployment Guide: Apps in Image + Persistent Volumes

This configuration implements the best of both worlds:

• Apps baked into Docker image for consistency and fast deployments
• Site data in persistent volumes for data safety and persistence

Architecture Overview

What's in the Image (Built once, reusable):

• ✅ Frappe and ERPNext applications
• ✅ All Python dependencies
• ✅ Custom apps (if configured)
• ✅ Basic directory structure

What's in Persistent Volumes:

• ✅ Site configurations (sites/[site-name]/site_config.json)
• ✅ Uploaded files (sites/[site-name]/public/files/)
• ✅ Private files (sites/[site-name]/private/files/)
• ✅ Site-specific customizations
• ✅ Database backups
• ✅ Application logs

Deployment Steps

1. Set Required Environment Secrets in Zerops

# In Zerops Dashboard > Project > Environment Variables
db_password=YourSecureDbPassword123
admin_password=YourAdminPassword123
site_name=your-domain.com

2. Deploy the Configuration

1. Import the zerops.yml file to Zerops
2. Zerops will build all services using Dockerfile.zerops
3. Each service will run the initialization script on startup
4. Site will be automatically created if it doesn't exist

3. Automatic Initialization Process

On first deployment, each container will:

1. Build Phase (runs once during image creation):

   • Install Frappe/ERPNext apps into image
   • Copy initialization scripts
   • Set proper permissions

2. Runtime Phase (runs on every container start):

   • Backend service: Full site initialization (creates site, installs ERPNext)
   • Other services: Light initialization (just checks if site exists)
   • Configure database and Redis connections
   • Wait for database to be ready (backend only)
   • Set proper permissions and configurations

Benefits of This Approach

✅ Container Restart Resilience

• Site data survives container restarts/crashes
• No manual intervention required
• Fast recovery times

✅ Consistent App Deployments

• Apps are identical across all containers
• No version drift between services
• Easy to update apps (rebuild image)

✅ Zero-Downtime Updates

• App updates: rebuild image, rolling update
• Site data preserved during updates
• Database migrations handled automatically

✅ Backup & Recovery

• Simple volume snapshots for site data
• Database backups work seamlessly
• Easy disaster recovery

✅ Scalability

• New containers start with same apps
• Shared persistent volume for site data
• Auto-scaling works out of the box

File Structure

/home/frappe/frappe-bench/
├── apps/                    # Apps (in image)
│   ├── frappe/             # Frappe framework
│   └── erpnext/            # ERPNext app
├── sites/                  # Site data (persistent volume)
│   ├── apps.txt            # List of installed apps
│   ├── common_site_config.json
│   └── your-domain.com/    # Your site directory
│       ├── site_config.json
│       ├── public/files/   # Uploaded files
│       └── private/files/  # Private files
└── logs/                   # Application logs (persistent volume)

Common Operations

Adding New Custom Apps

1. Update Dockerfile.zerops:

   RUN bench get-app --branch main custom_app https://github.com/user/custom_app.git
   

2. Redeploy services (Zerops will rebuild image)

3. Install app on site (automatic or manual):

   bench --site your-domain.com install-app custom_app
   

Updating Frappe/ERPNext Version

1. Update version in Dockerfile.zerops:

   FROM frappe/erpnext:v16.0.0
   

2. Update zerops.yml environment:

   ERPNEXT_VERSION: v16.0.0
   

3. Redeploy - migrations run automatically

Manual Site Operations

Access any service terminal in Zerops dashboard:

# Navigate to bench directory
cd /home/frappe/frappe-bench

# Run migrations
bench --site your-domain.com migrate

# Create new site
bench new-site newsite.com --install-app erpnext

# Install custom app
bench --site your-domain.com install-app custom_app

# Backup site
bench --site your-domain.com backup --with-files

# Console access
bench --site your-domain.com console

Troubleshooting

Site Not Created Automatically

• Check environment variables are set correctly
• Check database connectivity
• Review container logs in Zerops dashboard
• Manually run: /home/frappe/init-site.sh

Permission Issues

• Persistent volumes should be owned by frappe:frappe
• Run: chown -R frappe:frappe /home/frappe/frappe-bench/sites

App Installation Issues

• Verify apps are in the image: ls /home/frappe/frappe-bench/apps
• Check apps.txt: cat /home/frappe/frappe-bench/sites/apps.txt
• Manually install: bench --site [site] install-app [app]

Database Connection Issues

• Verify database service is running
• Check environment variables
• Test connection: mysql -h$DB_HOST -P$DB_PORT -uroot -p$DB_PASSWORD

Monitoring

Health Checks

• All services have health checks configured
• Monitor in Zerops dashboard
• Backend: /api/method/ping
• WebSocket: /socket.io/

Logs

• Application logs in persistent volume: /home/frappe/frappe-bench/logs
• Container logs in Zerops dashboard
• Database logs in MariaDB service logs

Performance

• Monitor resource usage in Zerops dashboard
• Auto-scaling configured based on CPU/memory
• Adjust container limits as needed

This hybrid approach gives you the reliability of persistent data with the consistency of containerized applications!