Peppermint Ticketing Software for help desk technicians.

-

Peppermint Ticketing

Peppermint is a modern, open-source help desk and issue tracking system built for IT teams, MSPs, and internal support departments that want a self-hosted, lightweight, and privacy-controlled solution.

Peppermint prioritizes:

  • Simplicity and speed

  • Developer freedom

  • Data sovereignty

  • Low infrastructure footprint

It’s designed for small to medium-sized teams who want something modern, minimalistic, and powerful — without being locked into enterprise subscriptions or bulky frameworks.

Architecture Overview

Peppermint’s backend is written primarily in TypeScript (Node.js), with a PostgreSQL database and a React-based frontend.
This makes it modular, fast, and compatible with modern deployment standards such as Docker, Kubernetes, and cloud instances (AWS, Linode, DigitalOcean, etc.).

Architecture Components

ComponentTechnology / Purpose


Backend =>Node.js (Express / Nest-like structure)
Database =>PostgreSQL (relational, handles tickets, users, roles, settings)
Frontend =>React + TailwindCSS (provides modern responsive UI)
Authentication =>Local accounts, with optional external providers (GitHub, Google planned)
Email handler =>IMAP for inbound, SMTP for outbound
Storage =>Local or S3-compatible object storage (for attachments)
Containerization =>Fully Docker-ready (docker-compose.yml included)

Ticket Lifecycle

Peppermint organizes support tasks around tickets — each representing a client request, issue, or report.

A typical ticket workflow:

  1. Ticket Creation

    • Tickets can be created by:

      • Clients via email (auto-parsed via IMAP)

      • Agents via the dashboard

      • API requests from other tools or chatbots

  2. Ticket Assignment

    • Tickets can be assigned manually to agents or automatically based on departments or tags (optional plugin).

  3. Communication Thread

    • Each ticket forms a threaded conversation between support and the customer.

    • Supports Markdown formatting, file uploads, internal notes, and status changes.

  4. Status & Labels

    • Default statuses: Open, In Progress, Pending, Closed.

    • Admins can create custom labels or priorities (e.g., Critical, Low, Scheduled).

  5. Resolution & Archiving

    • Once a ticket is resolved, it’s closed but remains searchable for auditing or training purposes.

User Roles & Access Control

Peppermint defines clear roles with different privileges:

RoleCapabilities
Admin =>Full system control, configuration, user management, integrations
Agent =>Manage and respond to tickets, add internal notes, assign or escalate
Client/User =>Submit tickets, reply to their own tickets, view status updates
Viewer (optional) =>Read-only view for reports or monitoring

Access is controlled via role-based permissions and token authentication.

Communication Channels

Peppermint’s design focuses on multi-channel ticket creation while maintaining simplicity:

  • Email-to-ticket conversion via IMAP/SMTP.

  • Web dashboard ticket submission.

  • API endpoints for integration with chatbots or third-party systems (e.g., Slack bots or customer portals).

Future roadmap discussions include integrating:

  • Live chat widget.

  • Webhook-based ticket generation (for monitoring tools like Zabbix, Grafana, or Uptime Kuma).

Interface & User Experience

Peppermint has one of the cleanest UIs among open-source help desks.

Interface Highlights

  • Dark and Light themes: Peppermint light & dark, Solarized light, Forest, Material Light and Github light.

  • Dashboard with live counters (open tickets, response time, SLA indicators)

  • Real-time notifications for updates and ticket assignments

  • Search bar and filtering system (by ID, keyword, client, label, etc.)

  • Keyboard shortcuts for ticket navigation

  • Integrated Markdown editor for replies and notes

The design feels similar to Notion or Linear — intuitive, smooth animations, and a focus on text readability.

Built-In Utilities

Peppermint includes internal tools that enhance the workflow:

  1. Notebook – A Markdown-based private documentation space for agents. Ideal for jotting internal procedures or notes.

  2. To-Do Lists – Agents can manage personal tasks or ticket follow-ups.

  3. History Log – Tracks every action (assignment, reply, tag, etc.) for auditing.

  4. Statistics Panel – Displays current ticket distribution by status, agent load, and response times.

  5. Email Templates – Customizable automatic replies and notification emails.

  6. Custom Branding – Add your organization’s name, logo, and colors.

Integration Possibilities

Peppermint offers an API and integration options:

  • Webhooks – Triggered on ticket creation, update, or closure.

  • REST API – Full CRUD access for tickets, users, and messages.

  • Email Parser – Converts incoming emails into structured tickets.

  • Third-party apps – Integration with monitoring systems, bots, or CRMs.

  • Zapier / n8n compatibility – Via webhooks or API calls.

Security Model

Peppermint focuses on security through a combination of best practices:

  • Passwords hashed via bcrypt.

  • HTTPS enforced (recommended).

  • CSRF & CORS protection built-in.

  • Token-based authentication (JWT).

  • Strict role-based access controls.

  • Optional IP whitelisting for admin access (manual config).

  • Attachments stored outside webroot for better data protection.

For self-hosters, regular patching and Docker updates are crucial for maintaining security.

Requirements.

  1. Lightweight footprint: Requires minimal resources — can run on 1-2GB RAM VPS.

  2. Modern UI: Comparable to commercial tools, unlike older open-source helpdesks (osTicket, OTRS).

  3. Custom data ownership: 100% local control over databases, tickets, and attachments.

  4. Open API: Enables easy automation and custom scripts.

  5. Active developer community: Frequent commits and community input.

  6. Markdown support: Clean communication formatting and internal note-taking.

  7. Flexible branding: Perfect for MSPs or IT consultants who want white-label ticketing.

Limitations.

  • No native mobile app yet (responsive web app works fine though).

  • Limited reporting dashboards (custom SQL queries or external BI tools needed).

  • No built-in SLA policy engine (planned feature).

  • Manual setup for mail parsing — advanced IMAP/SMTP configs required.

  • Community support — depends on GitHub Issues and Discord; no official enterprise support plan.

Use Cases

  • Internal IT Help Desk: For managing employee support tickets.

  • Managed Service Providers (MSPs): For tracking client issues.

  • Educational institutions: Handling student and staff tech requests.

  • Web hosting companies: Supporting hosting customers.

  • Small businesses: Centralizing client requests without heavy SaaS fees.

Roadmap & Community

According to community posts and GitHub milestones, the roadmap includes:

  • Built-in Knowledge Base module

  • Chat widget for websites

  • Time tracking & SLA reports

  • 2FA & SSO

  • Multi-language support

  • Audit logs and advanced reporting

The project is led by Peppermint Lab, with an active GitHub repository and self-hosted documentation portal at docs.peppermint.sh, click here to check the official documentation.

Setting up & Installation & Hands-on.

  1. using docker: I am using kali Linux for this installation, firstly we need docker and docker-compose to run peppermint on our host, using the following commands by kali, we have to update our repo and use docker.io instead of docker otherwise we would end up in installing the container version of docker.
sudo apt update
sudo apt install -y docker.io

Then we run it using systemctl.

sudo systemctl enable docker --now
sudo docker

Then you can add your user to the docker group: 
sudo usermod -aG docker $USER

Second you need to create the .yaml file to install the docker images, naming it docker-compose.yaml



Copy/paste the file content from the peppermint documentation side over here => click me

Then use your favorite file editor to edit the config file in order to add your localhost in case you want to run it locally. 

Just like that 


insert the BASE_URL: "http://localhost:8080" #optional or #API_URL
Save & Close
Then run it with this command: "sudo docker-compose up"


Look for the "Network" field to get the url to access the peppermint portal. 

Login with admin@admin.com/1234



This would be the main dashboard. From here you can add users, clients, admins, change theme, open tickets.

And as an admin you can see the users, clients, email queues, you can also add webhooks for external services notifications using POST requests, you can setup SMTP settings for outbound and do Auth using OIDC or OAuth, and saml soon.

The admin panel also provides access to a "roles feature" where you can make custom roles with specific permission of your choosing.

You can also access the logs and see what is going on behind the scenes!

2. you can use one-liner installation if you got a VPS subscription somewhere like Linode

using the following command:
curl -sSL -o deployer.sh https://deploy.spearmint.sh && chmod +x deployer.sh && ./deployer.sh


Update: on the latest peppermint updates you dont need to insert BASE_URL or API_URL values into the docker compos file, and if you do you get an Unauthorized access response, the tool will already give you the url address to access the peppermint portal. 

Comments

Post a Comment

Popular posts from this blog

Common Network Commands: IP R

-
IP R Command Overview The `ip r` command is part of the `iproute2` package in Linux systems. It is used for displaying and manipulating the routing table, which determines how network packets are directed to their destinations. This command is vital for network configuration, management, and troubleshooting. Origin and Development The `iproute2` package was created to replace the older `net-tools` package, which included commands like `ifconfig` and `route`. The `ip` command provides a more unified interface for network management, supporting advanced features and modern networking protocols. It offers better capabilities for managing complex networking scenarios, making it a crucial tool for system and network administrators. Basic Functionality The `ip r` command serves several functions: - Displays current routing table entries. - Shows destination networks, gateways, and associated interfaces. - Allows for the addition, deletion, and modification of routes. Key Command Syntax 1. Di...
Read more

Junior Security Analyst Intro

-
Why SOC Analyst L1 is Considered a Triage Specialist. A Level 1 Security Operations Center (SOC) Analyst is often regarded as a triage specialist because they are the first responders to cybersecurity alerts. Much like how a triage nurse assesses patients' conditions in a hospital, a Level 1 SOC Analyst evaluates and categorizes alerts generated by security tools to determine their severity and prioritize response efforts. Their primary focus is to: Filter Noise: Modern networks generate massive amounts of data, with many false positives. SOC L1 analysts must sift through this data to identify real threats. Categorize Alerts: Assign severity levels to incidents, such as low, medium, or high priority. Initial Response: Perform basic investigations (e.g., checking IP addresses, scanning logs) and decide whether to escalate incidents to Level 2 or 3 analysts. This role is vital because it ensures that high-priority threats are addressed quickly and resources are allocated ...
Read more

Example of A Day in the Life of a Junior (Associate) Security Analyst

-
The day begins early for the Junior Security Analyst, stepping into the office or logging into their remote workstation. The quiet hum of servers and the glow of multiple screens set the stage for another day at the heart of the cybersecurity battlefield. Their first task is to review the handover notes from the previous shift or the daily briefing. This update includes summaries of unresolved incidents, ongoing investigations, and any notable changes in the organization’s threat landscape. Equipped with this crucial information, the analyst prepares to navigate a world where even the smallest anomaly could signify a major threat. Logging into the array of tools—a Security Information and Event Management (SIEM) platform, endpoint detection systems, firewalls, and intrusion detection/prevention systems (IDS/IPS)—the analyst is immediately immersed in the flow of alerts. Every beep, flash, and log entry represents a potential threat. The first challenge is triage. Like a digital detecti...
Read more