Deploying ErpNext

Introduction

ErpNext is a powerful, open-source Enterprise Resource Planning (ERP) platform built on the Frappe Framework. It provides comprehensive business management solutions including accounting, inventory management, CRM, project management, HR, and manufacturing modules. As a modern, web-based ERP system, ErpNext offers an intuitive interface and extensive customization capabilities, making it ideal for businesses of all sizes looking to streamline their operations.

Deploying ErpNext on Klutch.sh provides you with a scalable, reliable cloud infrastructure that handles the complexity of container orchestration, allowing you to focus on configuring and using your ERP system. With Klutch.sh’s support for persistent storage, environment variable management, and automatic Dockerfile detection, you can deploy a production-ready ErpNext instance in minutes.

This comprehensive guide walks you through deploying ErpNext on Klutch.sh using Docker, covering everything from initial setup to production best practices. You’ll learn how to configure persistent volumes for data retention, set up database connections, manage environment variables, and optimize your deployment for security and performance.

---

Why Deploy ErpNext on Klutch.sh?

• Automatic Dockerfile Detection: Klutch.sh automatically detects and builds from your Dockerfile, simplifying the deployment process
• Persistent Storage: Easily attach volumes to persist your ERP data, documents, and configuration files
• GitHub Integration: Deploy directly from your GitHub repository with automatic builds on push
• Environment Management: Securely manage database credentials and API keys through environment variables
• Scalability: Scale your ErpNext deployment as your business grows
• Cost-Effective: Pay only for the resources you use with transparent pricing

---

Prerequisites

Before you begin deploying ErpNext on Klutch.sh, ensure you have the following:

• A Klutch.sh account - Sign up here if you haven’t already
• A GitHub account with a repository for your ErpNext deployment
• Basic understanding of Docker and containerization concepts
• Familiarity with ERP systems and database management
• A MariaDB or PostgreSQL database (can be deployed separately on Klutch.sh)

---

Understanding ErpNext Architecture

ErpNext follows a multi-tier architecture consisting of:

• Web Server: Serves the frontend application (typically Nginx)
• Application Server: Runs the Frappe/ErpNext Python application
• Background Workers: Process background jobs and scheduled tasks
• Database: Stores all application data (MariaDB or PostgreSQL)
• Redis: Handles caching and real-time communication
• SocketIO: Enables real-time notifications

For a production deployment on Klutch.sh, we’ll use the official ErpNext Docker images which bundle these components efficiently.

---

Deployment Steps

Step 1: Prepare Your GitHub Repository

First, create a new GitHub repository for your ErpNext deployment:

mkdir erpnext-deployment
cd erpnext-deployment
git init

Create a .gitignore file to exclude sensitive and unnecessary files:

# Environment variables
.env
*.env

# Logs
logs/
*.log

# Database files (if using SQLite for testing)
*.db
*.sqlite

# Node modules and dependencies
node_modules/

Commit and push your initial structure to GitHub:

git add .
git commit -m "Initial ErpNext deployment setup"
git remote add origin https://github.com/yourusername/erpnext-deployment.git
git push -u origin main

Step 2: Create Your Dockerfile

Create a Dockerfile in the root of your repository. Klutch.sh will automatically detect this file and use it for building your container.

Here’s a comprehensive Dockerfile for ErpNext:

# Use the official ErpNext image as base
FROM frappe/erpnext:latest

# Set the working directory
WORKDIR /home/frappe/frappe-bench

# Create necessary directories for persistent data
RUN mkdir -p sites assets logs

# Copy any custom apps or configurations (if needed)
# COPY ./custom_apps /home/frappe/frappe-bench/apps/custom_apps

# Set proper permissions
RUN chown -R frappe:frappe /home/frappe/frappe-bench

# Expose the application port
# ErpNext typically runs on port 8000
EXPOSE 8000

# The default command starts the ErpNext application
# This can be overridden with environment variables
CMD ["start"]

For a production-ready deployment with a custom startup script, create a more advanced Dockerfile:

FROM frappe/erpnext:latest

# Install additional dependencies if needed
USER root
RUN apt-get update && apt-get install -y \
    curl \
    wget \
    && rm -rf /var/lib/apt/lists/*

# Switch back to frappe user
USER frappe

WORKDIR /home/frappe/frappe-bench

# Create required directories
RUN mkdir -p sites/assets logs config

# Copy custom configuration files (if they exist)
# COPY --chown=frappe:frappe ./config/common_site_config.json /home/frappe/frappe-bench/sites/common_site_config.json

# Copy custom entrypoint script
COPY --chown=frappe:frappe docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh

EXPOSE 8000

ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["start"]

Step 3: Create a Custom Entrypoint Script (Optional but Recommended)

For better control over the startup process, create a docker-entrypoint.sh file:

#!/bin/bash
set -e

# Wait for database to be ready
echo "Waiting for database connection..."
until bench --site all migrate > /dev/null 2>&1 || true; do
  echo "Database not ready, waiting..."
  sleep 5
done

echo "Database is ready!"

# Run migrations if needed
if [ "$RUN_MIGRATIONS" = "true" ]; then
  echo "Running database migrations..."
  bench --site all migrate
fi

# Set up new site if SITE_NAME is provided and site doesn't exist
if [ ! -z "$SITE_NAME" ] && [ ! -d "sites/$SITE_NAME" ]; then
  echo "Creating new site: $SITE_NAME"
  bench new-site "$SITE_NAME" \
    --admin-password "$ADMIN_PASSWORD" \
    --db-host "$DB_HOST" \
    --db-name "$DB_NAME" \
    --db-password "$DB_PASSWORD" \
    --install-app erpnext
fi

# Execute the main command
exec "$@"

Make the script executable:

chmod +x docker-entrypoint.sh

Step 4: Configure Your Database

ErpNext requires a MariaDB or PostgreSQL database. You can deploy a database on Klutch.sh separately.

For MariaDB deployment on Klutch.sh, create a separate app with the following configuration:

• Image: MariaDB official Docker image
• Port: 3306 (internal), accessible via TCP on port 8000
• Environment Variables:
  • MYSQL_ROOT_PASSWORD: Your root password
  • MYSQL_DATABASE: erpnext
  • MYSQL_USER: erpnext_user
  • MYSQL_PASSWORD: Your database password

Alternatively, you can use a managed database service and configure ErpNext to connect to it using environment variables.

Step 5: Push Your Code to GitHub

Commit all your files and push to GitHub:

git add Dockerfile docker-entrypoint.sh .gitignore
git commit -m "Add ErpNext Dockerfile and configuration"
git push origin main

Step 6: Create a New App in Klutch.sh

Now you’re ready to deploy on Klutch.sh:

1. Navigate to klutch.sh/app
2. Click “Create New App” or “New Project”
3. Connect your GitHub repository by selecting it from the list
4. Klutch.sh will automatically detect your Dockerfile in the root directory

Important: Klutch.sh automatically detects Dockerfiles in the root directory. You don’t need to manually specify Docker as a deployment option in the UI - it’s automatic.

Step 7: Configure Environment Variables

In the Klutch.sh dashboard, add the following environment variables for your ErpNext deployment:

Database Configuration:

• DB_HOST: The hostname of your database (e.g., mariadb-app.klutch.sh:8000 for a database deployed on Klutch.sh)
• DB_NAME: erpnext
• DB_PASSWORD: Your database password (mark as secret)
• MYSQL_ROOT_PASSWORD: Your MySQL root password (mark as secret)

ErpNext Configuration:

• SITE_NAME: Your ErpNext site name (e.g., example-app.klutch.sh)
• ADMIN_PASSWORD: Password for the administrator account (mark as secret)
• FRAPPE_SITE_NAME_HEADER: Your site name
• RUN_MIGRATIONS: true (for first deployment)

Optional Configuration:

• REDIS_CACHE: redis://redis:6379/0 (if using a separate Redis instance)
• REDIS_QUEUE: redis://redis:6379/1
• REDIS_SOCKETIO: redis://redis:6379/2

Nixpacks Environment Variables (if you need to customize build/start commands):

• NIXPACKS_START_CMD: Custom start command if needed
• NIXPACKS_BUILD_CMD: Custom build command if needed

Step 8: Configure Persistent Volumes

ErpNext requires persistent storage to maintain your data across deployments. In the Klutch.sh dashboard:

1. Navigate to your app’s Volumes section
2. Click “Add Volume”
3. Configure the following mount paths and sizes:

Sites Directory (Essential):

• Mount Path: /home/frappe/frappe-bench/sites
• Size: 10GB minimum (adjust based on your data needs)

Logs Directory (Recommended):

• Mount Path: /home/frappe/frappe-bench/logs
• Size: 5GB

Assets Directory (Optional but recommended):

• Mount Path: /home/frappe/frappe-bench/sites/assets
• Size: 5GB

Important: When creating volumes in Klutch.sh, you only need to specify the mount path and size. The platform handles volume naming automatically.

Step 9: Configure Network Settings

ErpNext requires HTTP traffic for web access:

1. In the Klutch.sh dashboard, go to your app’s Network settings
2. Select HTTP as the traffic type
3. Set the internal port to 8000 (ErpNext’s default port)

ErpNext’s web interface should be accessible via HTTP on port 8000. If you’re deploying the database separately, that service should use TCP traffic on port 8000 for database connections.

Step 10: Deploy Your Application

With everything configured:

1. Review your settings in the Klutch.sh dashboard
2. Click “Deploy” or “Create”
3. Klutch.sh will:
   • Clone your repository from GitHub
   • Detect your Dockerfile automatically
   • Build the Docker image
   • Create the container with your configuration
   • Attach persistent volumes
   • Start the application

The deployment process typically takes 3-5 minutes. You can monitor the build logs in real-time through the dashboard.

Step 11: Verify Your Deployment

Once deployed, verify your ErpNext installation:

1. Access your application at https://your-app.klutch.sh (or your configured domain)
2. You should see the ErpNext login page
3. Log in with:
   • Username: Administrator
   • Password: The password you set in ADMIN_PASSWORD

If you encounter any issues, check the application logs in the Klutch.sh dashboard.

Step 12: Initial ErpNext Configuration

After successful deployment and login:

1. Complete the setup wizard to configure your company details
2. Set up your chart of accounts
3. Configure users and permissions
4. Set up your fiscal year and currency
5. Install any additional apps or modules you need

---

Sample Configuration Files

common_site_config.json

Create a config/common_site_config.json file for shared site configuration:

{
  "db_host": "your-db-host",
  "db_port": 3306,
  "redis_cache": "redis://redis:6379/0",
  "redis_queue": "redis://redis:6379/1",
  "redis_socketio": "redis://redis:6379/2",
  "socketio_port": 9000,
  "webserver_port": 8000,
  "allow_tests": false,
  "maintenance_mode": 0,
  "server_script_enabled": true,
  "disable_website_cache": false
}

Note: This file can contain sensitive information. Use environment variables in production instead of hardcoding values.

---

Environment Variables Reference

Required Variables

Variable	Description	Example
DB_HOST	Database hostname	mariadb.example.com
DB_NAME	Database name	erpnext
DB_PASSWORD	Database password	securepassword123
SITE_NAME	ErpNext site name	example-app.klutch.sh
ADMIN_PASSWORD	Admin password	adminpass123

Optional Variables

Variable	Description	Default
RUN_MIGRATIONS	Run migrations on startup	false
REDIS_CACHE	Redis cache URL	redis://localhost:6379/0
REDIS_QUEUE	Redis queue URL	redis://localhost:6379/1
WORKERS	Number of worker processes	2

---

Persistent Storage Best Practices

What to Store

Critical Data (Must Persist):

• Site configurations in /home/frappe/frappe-bench/sites
• Uploaded files and attachments
• Custom reports and scripts
• User data and preferences

Recommended to Persist:

• Application logs in /home/frappe/frappe-bench/logs
• Backups directory
• Custom apps and modifications

Backup Strategy

Regular backups are essential for any ERP system:

1. Database Backups: Use bench backup command or database-native tools
2. File Backups: Backup the sites directory regularly
3. Configuration Backups: Version control your configuration files

# Manual backup command (run in container)
bench --site your-site backup --with-files

Set up automated backups using Klutch.sh’s volume snapshot features or external backup solutions.

---

Database Configuration

Using MariaDB (Recommended)

MariaDB is the recommended database for ErpNext. Deploy it on Klutch.sh:

1. Create a new app with MariaDB image
2. Use TCP traffic type
3. Set internal port to 3306
4. Create volumes for /var/lib/mysql
5. Note the connection details for your ErpNext configuration

Using PostgreSQL

ErpNext also supports PostgreSQL:

1. Deploy PostgreSQL on Klutch.sh similarly to MariaDB
2. Update environment variables accordingly
3. Ensure the PostgreSQL driver is installed in your ErpNext image

Database Performance Tips

• Allocate sufficient RAM to your database instance (minimum 2GB recommended)
• Enable query caching
• Regular maintenance with OPTIMIZE TABLE
• Monitor slow queries and add indexes as needed

---

Production Best Practices

Security

1. Use Strong Passwords: Never use default passwords in production
2. Environment Variables: Store all secrets as environment variables, never in code
3. HTTPS Only: Ensure all traffic uses HTTPS (Klutch.sh provides this by default)
4. Regular Updates: Keep ErpNext and its dependencies up to date
5. Access Control: Implement proper user roles and permissions
6. Database Security: Use separate database users with minimal required permissions

Performance Optimization

1. Resource Allocation:

   • Minimum 2GB RAM for small deployments
   • 4GB+ RAM for medium to large deployments
   • Adjust based on user count and transaction volume

2. Caching:

   • Use Redis for caching
   • Enable browser caching for static assets
   • Configure CDN for asset delivery if needed

3. Database Tuning:

   • Optimize database queries
   • Regular database maintenance
   • Index frequently queried fields

4. Background Workers:

   • Scale worker processes based on job queue length
   • Monitor background job execution times

Monitoring

Monitor the following metrics:

• Application Health: Response times, error rates
• Database Performance: Query times, connection pool usage
• Resource Usage: CPU, memory, disk I/O
• Background Jobs: Queue length, failed jobs
• Storage: Disk usage for volumes

Use Klutch.sh’s built-in monitoring tools or integrate with external monitoring solutions.

Scaling Strategies

As your business grows, consider:

1. Vertical Scaling: Increase instance size for more CPU/RAM
2. Horizontal Scaling: Deploy multiple ErpNext instances behind a load balancer
3. Database Scaling: Use read replicas for reporting queries
4. Caching Layer: Implement Redis or Memcached for improved performance

---

Troubleshooting

Common Issues and Solutions

Application Won’t Start

Symptoms: Container keeps restarting or fails to start

Solutions:

• Check logs in Klutch.sh dashboard
• Verify database connection strings
• Ensure all required environment variables are set
• Check that persistent volumes are properly mounted

Database Connection Errors

Symptoms: “Could not connect to database” errors

Solutions:

• Verify DB_HOST points to correct database service
• Check database credentials in environment variables
• Ensure database service is running
• For TCP connections, verify port 8000 is accessible

Permission Errors

Symptoms: “Permission denied” errors in logs

Solutions:

• Verify volume permissions
• Check that frappe user has write access to mounted directories
• Review Dockerfile user configuration

Slow Performance

Symptoms: Application is slow or unresponsive

Solutions:

• Check resource usage (CPU/memory) in dashboard
• Review database query performance
• Increase instance size if needed
• Optimize database indexes
• Enable Redis caching

Failed Migrations

Symptoms: Database schema errors or migration failures

Solutions:

• Backup database before migrations
• Run migrations manually: bench --site all migrate
• Check ErpNext version compatibility
• Review migration logs for specific errors

Getting Help

If you encounter issues:

1. Check the ErpNext Community Forum
2. Review ErpNext GitHub Issues
3. Consult the Official ErpNext Documentation
4. Contact Klutch.sh support for platform-specific questions

---

Updating ErpNext

To update your ErpNext deployment:

1. Backup First: Always backup your database and files before updating
2. Update Dockerfile: Change the image tag to the desired version
3. Commit and Push: Push changes to GitHub
4. Trigger Rebuild: Klutch.sh will automatically rebuild on push
5. Run Migrations: Set RUN_MIGRATIONS=true for the deployment
6. Verify: Test the application thoroughly after update

Example Dockerfile change for updating:

# Update from latest to specific version
FROM frappe/erpnext:v14.0.0

---

Advanced Configuration

Custom Apps

To add custom Frappe apps to your ErpNext deployment:

1. Clone your custom app into the apps directory
2. Update Dockerfile to install the app:

FROM frappe/erpnext:latest

WORKDIR /home/frappe/frappe-bench

# Copy custom app
COPY --chown=frappe:frappe ./apps/custom_app apps/custom_app

# Install the custom app from local directory
RUN bench get-app file:///home/frappe/frappe-bench/apps/custom_app
RUN bench --site all install-app custom_app

Multi-Site Configuration

ErpNext supports multiple sites in a single deployment:

1. Create sites configuration in your entrypoint script
2. Use separate databases for each site
3. Configure site routing based on domain names

Email Configuration

Configure email for notifications and communications:

# Add to site_config.json
{
  "mail_server": "smtp.gmail.com",
  "mail_port": 587,
  "use_tls": true,
  "mail_login": "your-email@example.com",
  "mail_password": "your-app-password"
}

Store email credentials as environment variables and inject them at runtime.

---

Resources

Official Documentation

• ErpNext Official Website
• ErpNext Documentation
• ErpNext GitHub Repository
• Frappe Framework Documentation

Klutch.sh Resources

• Klutch.sh Quick Start Guide
• Persistent Volumes Guide
• Deployment Concepts
• Networking and Traffic Management

Community

• ErpNext Community Forum
• GitHub Discussions

---

Conclusion

Deploying ErpNext on Klutch.sh provides a robust, scalable solution for managing your business operations in the cloud. With automatic Dockerfile detection, persistent storage, and seamless GitHub integration, you can focus on configuring and using your ERP system rather than managing infrastructure.

This guide covered everything from initial setup to production best practices, ensuring your ErpNext deployment is secure, performant, and maintainable. As your business grows, Klutch.sh scales with you, providing the flexibility and reliability needed for mission-critical ERP systems.

For additional support or advanced configurations, consult the resources section or reach out to the Klutch.sh and ErpNext communities.

Happy deploying!