Skip to main content
This guide walks you through setting up Frappe Helpdesk for local development. This setup is ideal for contributing to the project or developing custom features.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.14 or higher
  • Node.js 18 or higher
  • MariaDB 10.8+
  • Redis
  • Git
  • Yarn package manager

​
Installation Steps

1

Install Frappe Bench

Follow the official Frappe Framework Installation Guide to set up a frappe-bench directory.This will install the Frappe Framework and configure your development environment with all necessary dependencies.
2

Start the Frappe server

Navigate to your bench directory and start the development server:
cd frappe-bench
bench start
This starts multiple services:
  • Web server on port 8000
  • SocketIO server for real-time updates
  • Redis queues for background jobs
  • Scheduler for cron jobs
Keep this terminal running and open a new terminal for subsequent steps.
3

Create a new site

In a separate terminal, create a new site for development:
bench new-site helpdesk.test
You’ll be prompted to set the MySQL root password and create an administrator password.
4

Map site to localhost

Add the site to your hosts file for easy access:
bench --site helpdesk.test add-to-hosts
This allows you to access the site at http://helpdesk.test:8000
5

Install Telephony app

Frappe Helpdesk requires the Telephony app as a dependency:
bench get-app https://github.com/frappe/telephony
This clones the Telephony app into frappe-bench/apps/telephony
6

Get Helpdesk app

Clone the Helpdesk repository:
bench get-app https://github.com/frappe/helpdesk
The app will be cloned to frappe-bench/apps/helpdesk
7

Install Helpdesk on your site

Install the Helpdesk app on your site:
bench --site helpdesk.test install-app helpdesk
This installs all DocTypes, creates database tables, and runs setup scripts.
8

Build frontend assets

Build the frontend application:
bench build --app helpdesk
This compiles the Vue 3 frontend using Vite.
9

Access the application

Open your browser and navigate to:
http://helpdesk.test:8000/helpdesk
Login with:
  • Username: Administrator
  • Password: (the password you set during site creation)

​
Frontend Development Setup

For active frontend development with hot module replacement (HMR):
1

Navigate to the frontend directory

cd frappe-bench/apps/helpdesk/desk
All frontend code is located in the desk/ directory.
2

Install dependencies

yarn install
This installs all npm packages including Vue 3, frappe-ui, Tailwind CSS, and development tools.
3

Start the Vite dev server

yarn dev
Or, to run on a specific host:
yarn dev --host helpdesk.test
The Vite dev server will start on port 8080 by default.
4

Access the dev server

Navigate to:
http://helpdesk.test:8080
You now have hot module replacement enabled. Changes to Vue components will reflect instantly in the browser.
The Frappe backend server (bench start) must remain running while developing the frontend. The Vite dev server proxies API requests to the backend server on port 8000.

​
Project Structure

Understanding the project layout: 
frappe-bench/
├── apps/
│   ├── frappe/              # Frappe Framework core
│   ├── telephony/           # Telephony app (dependency)
│   └── helpdesk/            # Frappe Helpdesk
│       ├── helpdesk/        # Python backend
│       │   ├── api/         # API endpoints
│       │   ├── helpdesk/    # DocTypes
│       │   ├── hooks.py     # App hooks and configuration
│       │   ├── utils.py     # Utility functions
│       │   └── search.py    # Search functionality
│       └── desk/            # Vue 3 frontend
│           ├── src/         # Frontend source code
│           │   ├── components/  # Vue components
│           │   ├── pages/       # Page components
│           │   ├── stores/      # Pinia stores
│           │   ├── router/      # Vue Router config
│           │   └── main.js      # Entry point
│           ├── package.json
│           ├── vite.config.js
│           └── tailwind.config.js
└── sites/
    └── helpdesk.test/       # Your development site

​
Common Development Tasks

​
Migrate database changes

After pulling updates or modifying DocTypes: 
bench --site helpdesk.test migrate

​
Clear cache

If you encounter stale data or weird behavior: 
bench --site helpdesk.test clear-cache

​
Restart the server

After modifying Python code: 
# Stop bench (Ctrl+C in the bench start terminal)
bench start

​
Rebuild frontend

To create a production build: 
bench build --app helpdesk

​
Console access

Access the Frappe console for debugging: 
bench --site helpdesk.test console

​
Run tests

Execute the test suite: 
bench --site helpdesk.test run-tests --app helpdesk

​
Debugging

​
Backend debugging

  1. Add print() statements or use frappe.log_error() in Python code
  2. Create a debug file at helpdesk/debug.py: 
    def execute():
    # Your debug code here
    print("Debug output")
  3. Run with: 
    bench --site helpdesk.test execute helpdesk.debug.execute

​
Frontend debugging

  • Use browser DevTools
  • Vue DevTools extension for component inspection
  • Check the Vite dev server terminal for build errors
  • Review Network tab for API request/response

​
Compatibility

Helpdesk BranchCompatible Frappe Version
mainversion-15, version-16
developdevelop branch

​
Next Steps

​
Troubleshooting

​
Port conflicts

If port 8000 or 8080 is already in use, you can configure different ports in frappe-bench/sites/common_site_config.json

​
Database connection errors

Verify MariaDB is running and the credentials in frappe-bench/sites/helpdesk.test/site_config.json are correct.

​
Module not found errors

Ensure all dependencies are installed: 
# For Python dependencies
bench setup requirements

# For JavaScript dependencies
cd apps/helpdesk/desk && yarn install

Build docs developers (and LLMs) love

Get started for freeTalk to us