Skip to main content

​
Installation Guide

Frappe Helpdesk offers two deployment options: managed hosting on Frappe Cloud for a hassle-free experience, or self-hosting for complete control over your infrastructure.

​
Frappe Cloud

The easiest way to get started with Frappe Helpdesk is through Frappe Cloud, a simple, user-friendly, and sophisticated open-source platform for hosting Frappe applications.

Zero Setup

No installation, configuration, or maintenance required

Automatic Updates

Always running the latest version with security patches

Monitoring Included

Built-in monitoring, backups, and performance optimization

Developer Tools

Full-featured platform to manage multiple deployments

​
Get Started on Frappe Cloud

1

Sign Up

Visit Frappe Cloud Helpdesk Signup and create your account.
2

Create Site

Follow the guided setup to provision your Frappe Helpdesk site. Your site will be ready in approximately 5 minutes.
3

Access Your Instance

Once deployed, access your helpdesk at:
https://your-site.frappe.cloud/helpdesk
Frappe Cloud handles all infrastructure management including installation, setup, upgrades, monitoring, maintenance, and support.

​
Self-Hosting

For organizations that need complete control over their infrastructure, Frappe Helpdesk can be self-hosted using Docker or a local development setup.

​
Production Deployment

Deploy a production-ready instance of Frappe Helpdesk using the easy install script:
1

Download the Easy Install Script

wget https://frappe.io/easy-install.py
This script automates the entire deployment process with all necessary configurations.
2

Run the Deployment Command

python3 ./easy-install.py deploy \
    --project=helpdesk_prod_setup \
    [email protected] \
    --image=ghcr.io/frappe/helpdesk \
    --version=stable \
    --app=helpdesk \
    --sitename=subdomain.domain.tld
Replace the following parameters:
  • [email protected]: Your email address for admin notifications
  • subdomain.domain.tld: Your domain name where Helpdesk will be hosted
The script sets up a production-ready instance in about 5 minutes with:
  • Docker containers for isolation
  • Nginx reverse proxy
  • SSL/TLS configuration
  • Database setup
  • Background workers
3

Access Your Instance

Once the script completes, access your helpdesk at:
https://subdomain.domain.tld/helpdesk
Ensure your server meets the minimum requirements:
  • 2 GB RAM (4 GB recommended)
  • 2 CPU cores
  • 20 GB disk space
  • Ubuntu 20.04 or later
  • Docker and Docker Compose installed

​
Development Setup

For development, testing, or contributing to Frappe Helpdesk, choose between Docker or a local setup.

​
Option 1: Docker Development Setup

Docker provides the fastest way to get a development environment running.
1

Prerequisites

Ensure you have the following installed:
2

Setup Project Directory

mkdir frappe-helpdesk
cd frappe-helpdesk

# Download the docker-compose file
wget -O docker-compose.yml https://raw.githubusercontent.com/frappe/helpdesk/develop/docker/docker-compose.yml

# Download the setup script
wget -O init.sh https://raw.githubusercontent.com/frappe/helpdesk/develop/docker/init.sh
3

Start the Containers

docker compose up -d
This command will:
  • Pull the required Docker images
  • Set up the database (MariaDB)
  • Configure Redis for caching and background jobs
  • Initialize the Frappe site
  • Start the development server
4

Access the Development Site

The site will be available at:
http://helpdesk.localhost:8000/helpdesk
Default credentials:
  • Username: Administrator
  • Password: admin
These credentials are for development only. Never use them in production!

​
Option 2: Local Development Setup

For a full local development environment with access to all Frappe Framework tools:
1

Install Frappe Bench

Follow the Frappe Framework Installation Guide to set up bench and create a frappe-bench directory.This involves:
  • Installing Python 3.10+
  • Setting up MariaDB
  • Installing Redis
  • Configuring Node.js and yarn
2

Start Frappe Services

cd frappe-bench
bench start
This starts:
  • Web server (port 8000)
  • WebSocket server (port 9000)
  • Redis servers
  • Background workers
3

Create a New Site

In a separate terminal window:
bench new-site helpdesk.test
You’ll be prompted to set a MariaDB root password and admin password.
4

Map Site to Localhost

bench --site helpdesk.test add-to-hosts
This adds the site to your /etc/hosts file for local access.
5

Install Required Apps

Frappe Helpdesk depends on the Telephony app:
# Get the Telephony app
bench get-app https://github.com/frappe/telephony

# Get the Helpdesk app
bench get-app https://github.com/frappe/helpdesk
6

Install Apps on Your Site

bench --site helpdesk.test install-app helpdesk
This:
  • Installs the Helpdesk app and its dependencies
  • Creates database tables (DocTypes)
  • Sets up default configurations
  • Installs demo data (optional)
7

Build Frontend Assets

bench build --app helpdesk
This compiles:
  • Vue 3 components
  • TypeScript files
  • CSS with Tailwind
  • Static assets
8

Access the Application

Open your browser and navigate to:
http://helpdesk.test:8000/helpdesk

​
Frontend Development Setup

For active frontend development with hot module replacement:
1

Navigate to Frontend Directory

cd frappe-bench/apps/helpdesk/desk
This directory contains:
  • Vue 3 source code (src/)
  • TypeScript configuration
  • Vite build configuration
  • Tailwind CSS setup
2

Install Dependencies

yarn install
This installs:
  • Vue 3.5+
  • frappe-ui components
  • TypeScript
  • Vite dev server
  • Tailwind CSS
  • All other dependencies from package.json
3

Start Vite Dev Server

# Basic dev server
yarn dev

# Or specify custom host
yarn dev --host helpdesk.test
The Vite dev server provides:
  • Hot module replacement (HMR)
  • Instant updates on code changes
  • Source maps for debugging
  • Fast builds with esbuild
4

Access Development Server

The frontend will be available at:
http://helpdesk.test:8080
All frontend code is in frappe-bench/apps/helpdesk/desk/. The structure includes:
  • src/components/ - Reusable Vue components
  • src/pages/ - Page-level components and routes
  • src/stores/ - Pinia state management
  • src/router/ - Vue Router configuration
  • src/composables/ - Reusable composition functions

​
Version Compatibility

Ensure you’re using compatible versions of Frappe Framework:
Helpdesk BranchCompatible Frappe Framework Version
mainversion-15, version-16
developdevelop branch
Using incompatible versions may result in unexpected behavior or errors.

​
Post-Installation Configuration

After installation, configure your Frappe Helpdesk instance:

Email Settings

Configure SMTP to send and receive emails:
  • Set up email accounts
  • Configure incoming email
  • Customize email templates

Create Agents

Add support agents:
  • Create agent profiles
  • Assign to teams
  • Set permissions and roles

Configure Teams

Organize agents into teams:
  • Create team structures
  • Set team leaders
  • Define team-specific workflows

Set Up SLAs

Define service level agreements:
  • Response time targets
  • Resolution time goals
  • Priority-based SLAs

​
Troubleshooting

​
Docker Issues

If containers fail to start: 
# Check container logs
docker compose logs -f

# Restart containers
docker compose restart

# Rebuild from scratch
docker compose down -v
docker compose up -d

​
Local Setup Issues

Port already in use: 
# Check what's using port 8000
lsof -i :8000

# Kill the process or change bench port
bench set-config -g http_port 8001
Database connection errors: 
# Restart MariaDB
sudo systemctl restart mariadb

# Check MariaDB status
sudo systemctl status mariadb
Frontend build errors: 
# Clear node modules and reinstall
cd frappe-bench/apps/helpdesk/desk
rm -rf node_modules
yarn install

# Clear Vite cache
rm -rf .vite

​
Permission Errors

# Fix file permissions
cd frappe-bench
sudo chown -R $USER:$USER .

# Reset site permissions
bench --site helpdesk.test set-admin-password <new-password>

​
Updating Frappe Helpdesk

​
Frappe Cloud

Updates are handled automatically. You can also trigger manual updates from the Frappe Cloud dashboard.

​
Self-Hosted

# Pull latest changes
cd frappe-bench/apps/helpdesk
git pull origin main

# Update site
cd ../..
bench --site helpdesk.test migrate

# Rebuild frontend
bench build --app helpdesk

# Restart bench
bench restart

​
Next Steps

Quickstart Guide

Learn how to create your first ticket and start using Frappe Helpdesk

Configuration

Customize settings, branding, and workflows

API Documentation

Integrate Frappe Helpdesk with your applications

Contributing

Contribute to the project on GitHub
For production deployments, always use the stable release from the main branch. The develop branch contains the latest features but may be unstable.

Build docs developers (and LLMs) love

Get started for freeTalk to us