Frappe CI/CD - Multi-Site Deployment

Automated build and deployment pipeline for Frappe/ERPNext with custom apps support. Deploy multiple isolated Frappe sites on a single server using GitHub Actions and Docker Compose.

🚀 Features

• ✅ Build custom Frappe images with your apps
• ✅ Deploy multiple independent Frappe sites
• ✅ Each site has isolated database, Redis, and volumes
• ✅ Easy site management with Docker Compose
• ✅ Automatic health checks and deployment verification

📋 Prerequisites

• GitHub account
• Docker and Docker Compose installed on your server
• Self-hosted GitHub Actions runner configured
• Docker Hub account (for storing images)

🛠️ Setup Instructions

Step 1: Fork the Repository

1. Click the Fork button at the top right of this repository
2. Clone your forked repository to your local machine

Step 2: Configure Custom Apps

Edit the apps.json file to include your custom Frappe apps. For example:

[
  {
    "url": "https://github.com/frappe/erpnext",
    "branch": "version-15"
  },
  {
    "url": "https://github.com/frappe/hrms",
    "branch": "version-15"
  },
  {
    "url": "https://github.com/your-org/your-custom-app",
    "branch": "main"
  }
]

Commit and push your changes:

git add apps.json
git commit -m "Add custom apps configuration"
git push origin main

Step 3: Configure GitHub Secrets

Add your Docker Hub credentials to GitHub Secrets:

1. Go to your repository on GitHub
2. Navigate to Settings → Secrets and variables → Actions
3. Click New repository secret and add:
   • DOCKER_USERNAME: Your Docker Hub username
   • DOCKER_PASSWORD: Your Docker Hub password/token

Step 4: Setup Self-Hosted Runner

Configure a self-hosted GitHub Actions runner on your server:

1. Go to Settings → Actions → Runners
2. Click New self-hosted runner
3. Follow the instructions to install and configure the runner on your server:

Note -> instead of ./run.sh. You have to run

./run.sh &

4. Verify the runner shows as Active in GitHub

🚢 Deploy a Frappe Site

Step 1: Trigger the Workflow

1. Go to Actions tab in your repository
2. Select Build and Deploy Frappe Custom App workflow
3. Click Run workflow

Step 2: Provide Deployment Parameters

Note -> If you are installing multiple apps then u have to provide argument using the syntax without any space->

  app1,app2,app3

Step 3: Access Your Site

After deployment completes (5-10 minutes), access your site:

http://localhost:<port>

Default credentials:

• Username: Administrator
• Password: admin (or your custom admin_password)

🔄 Deploy Multiple Sites

You can deploy multiple independent Frappe sites on the same server:

Example: Deploy 3 sites

Site Name	Port	Apps
development.local	8080	frappe,erpnext
staging.local	8081	frappe,erpnext,hrms
production.local	8082	frappe,erpnext,hrms,insights

Each site runs in complete isolation with:

• ✅ Separate database
• ✅ Separate Redis instances
• ✅ Separate volumes and data
• ✅ Independent scaling and management

Jenkins Pipeline Setup Guide

Prerequisites

1. Jenkins Plugins Required

Install these plugins in Jenkins (Manage Jenkins → Plugin Manager):

• Pipeline (Core pipeline plugin)
• Docker Pipeline (for Docker operations)
• Git (for SCM checkout)

2. Jenkins Node Configuration

Build Agent (any)

• Can run on any available Jenkins agent
• Requires Docker installed and accessible
• User must have permissions to run Docker commands

Deploy Agent (self-hosted)

• Must be labeled as self-hosted in Jenkins
• Configure in: Manage Jenkins → Nodes → [Your Node] → Configure → Labels
• Add label: self-hosted

3. Docker Hub Credentials Setup

1. Go to: Manage Jenkins → Credentials → System → Global credentials
2. Click Add Credentials
3. Configure:
   • Kind: Username with password
   • Scope: Global
   • Username: Your Docker Hub username
   • Password: Your Docker Hub password/token
   • ID: docker-hub-credentials (IMPORTANT: Must match the ID used in pipeline)
   • Description: Docker Hub Credentials

4. Required System Tools

Both build and deploy agents need:

# Docker
sudo apt-get update
sudo apt-get install -y docker.io docker-compose

# jq (for JSON validation)
sudo apt-get install -y jq

# netstat (for port checking)
sudo apt-get install -y net-tools

# Add jenkins user to docker group
sudo usermod -aG docker jenkins
sudo systemctl restart jenkins