Peppermint – angepasster Fork

Dieser Fork basiert auf dem archivierten Projekt Peppermint-Lab/peppermint (letzter Stand September 2025). Er behebt Fehler, die einen Build mit aktuellen Abhängigkeiten und den Login per OIDC/SSO verhindert haben, und ergänzt einige Funktionen. Die ursprüngliche README folgt weiter unten.

Änderungen gegenüber dem Original

Login per SSO (OIDC)

• SSO-Button wird angezeigt: /api/v1/auth/check und /api/v1/auth/oidc/callback sind jetzt ohne Token erreichbar. Vorher wurden beide von der globalen Authentifizierungsprüfung mit 401 Unauthorized abgewiesen, wodurch der Button auf der Loginseite fehlte und die Rückleitung vom Identity Provider scheiterte (apps/api/src/main.ts).
• Kein sofortiger Logout nach SSO-Login: Beim OIDC-Login werden User-Agent und IP-Adresse in der Sitzung gespeichert. Ohne diese Werte hat die Sitzungsprüfung die Sitzung als „Hijacking“ gewertet und gelöscht (apps/api/src/controllers/auth.ts).
• Button umbenannt: „Sign in with OIDC“ heißt jetzt „Sign in with SSO“.

Tickets

• Neuer Ticket-Typ „Change“ neben Bug, Feature, Incident usw., inklusive Datenbank-Migration.
• Fälligkeitsdatum (Due date):
  • optional beim Anlegen eines Tickets,
  • in der Ticket-Ansicht in der Seitenleiste jederzeit änderbar oder entfernbar,
  • in der Ticketliste als „Due TT/MM/JJJJ“, überfällige offene Tickets in Rot.
• Bearbeitungsstatus und Offen/Geschlossen sind verknüpft: Der Status „Done“ schließt ein Ticket, jeder andere Status öffnet es wieder. Umgekehrt setzt der Button zum Schließen den Status auf „Done“ und der Button zum Wiedereröffnen auf „Needs Support“. E-Mails, Benachrichtigungen und Webhooks werden in beiden Fällen gleich ausgelöst. Bestehende Tickets wurden per Migration angeglichen.
• Statusanzeige in der Ticket-Ansicht zeigt lesbare Namen („In Review“ statt „In_review“) und aktualisiert sich nach dem Schließen oder Wiedereröffnen.
• Schließdatum (Closed): Neues Feld closedAt, das beim Schließen eines Tickets gesetzt und beim Wiedereröffnen geleert wird. Außerdem wird updatedAt bei Statusänderungen jetzt tatsächlich aktualisiert.

Dashboard

• Spalte „Due Date“ in der Tabelle „Recent Issues“, überfällige Tickets in Rot.
• Bearbeitungsstatus statt „Open“ in der Tabelle „Recent Issues“ (Needs Support, In Progress, In Review, Hold) mit eigener Farbe; die Spalte ist sortierbar.
• Prioritäten werden angezeigt: Die Spalte „Priority“ war leer, weil das Dashboard nach „Low/Normal/High“ gesucht hat, gespeichert werden aber low/medium/high.
• Abschnitt „Closed Issues“ mit den zehn zuletzt geschlossenen Tickets, Spalte „Closed“ mit dem Schließdatum und Link „Show all“.
• Sortierbare Spalten in beiden Tabellen: Title, Priority, Created sowie Due Date bzw. Closed. Ein Klick sortiert, ein zweiter dreht die Richtung um. Leere Werte stehen immer am Ende.
• Filter „Assigned To“: Die Spaltenüberschrift ist ein Auswahlfeld, mit dem sich jede Tabelle auf einen Zuständigen oder auf nicht zugewiesene Tickets einschränken lässt. Die Sortierung bleibt dabei aktiv.

Build-Fixes

Da das Original-Dockerfile Abhängigkeiten ohne Lockfile installiert, brechen Builds mit heutigen Paketversionen ab. Behoben durch:

• TypeScript auf Version 5 festgelegt (dockerfile). TypeScript 7 ist mit Next.js 14 nicht kompatibel.
• Typprüfung und Linting beim Frontend-Build übersprungen (apps/client/next.config.js), da neuere Paketversionen strengere Typen mitbringen. Das Laufzeitverhalten ändert sich dadurch nicht.
• prosemirror-view auf 1.37.2 festgelegt (resolutions in apps/client/package.json). Ab 1.38 fehlt eine Funktion, die der Editor BlockNote 0.17 benötigt.

Image bauen

docker build -t peppermint-oidc:latest -f dockerfile .

Deployment (Docker Compose / Portainer-Stack)

services:
  peppermint_postgres:
    container_name: peppermint_postgres
    image: postgres:16
    restart: always
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: peppermint
      POSTGRES_PASSWORD: DB_PASSWORT
      POSTGRES_DB: peppermint
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U peppermint -d peppermint"]
      interval: 5s
      timeout: 5s
      retries: 10

  peppermint:
    container_name: peppermint
    image: peppermint-oidc:latest
    restart: always
    ports:
      - 127.0.0.1:3002:3000
      - 127.0.0.1:5003:5003
    depends_on:
      peppermint_postgres:
        condition: service_healthy
    environment:
      DB_USERNAME: peppermint
      DB_PASSWORD: DB_PASSWORT
      DB_HOST: peppermint_postgres
      DATABASE_URL: postgresql://peppermint:DB_PASSWORT@peppermint_postgres/peppermint
      SECRET: LANGER_ZUFAELLIGER_STRING

volumes:
  pgdata:

Hinweise:

• DATABASE_URL ist Pflicht. Das offizielle Image bringt dafür eine .env-Datei mit, die nicht im Repository enthalten ist.
• Postgres-Version festlegen. Mit postgres:latest (ab Version 18) passt der Volume-Pfad /var/lib/postgresql/data nicht mehr.
• Datenbank-Port nicht veröffentlichen. Peppermint erreicht die Datenbank intern über das Stack-Netzwerk.
• Kein $ in Passwörtern bzw. als $$ schreiben, da Compose $ als Variable interpretiert. Sonderzeichen in DATABASE_URL müssen URL-kodiert werden.
• POSTGRES_PASSWORD wirkt nur beim ersten Anlegen der Datenbank. Spätere Passwortänderungen per ALTER USER peppermint WITH PASSWORD '...'; im Container.
• Bei Updates des Stacks in Portainer „Re-pull image“ ausschalten, da das Image nur lokal existiert.
• Neue Migrationen werden beim Start des Containers automatisch angewendet.

SSO mit Authentik

1. In Authentik eine Application mit OAuth2/OpenID Provider anlegen:
   • Client type: Public (Peppermint sendet kein Client Secret, sonst Fehler invalid_client)
   • Redirect URI (Strict): https://<peppermint-domain>/auth/oidc
   • Scopes: openid, email, profile
2. In Peppermint unter Admin → Authentication → OIDC eintragen:
   • Issuer: https://<authentik-domain>/application/o/<slug>/ (exakt wie in der .well-known/openid-configuration)
   • Client ID aus Authentik
   • Redirect URI wie oben
3. Container neu starten, da die OIDC-Konfiguration zwischengespeichert wird.

Unbekannte E-Mail-Adressen legt Peppermint beim ersten SSO-Login automatisch als Nutzer ohne Admin-Rechte an. Den Zugang daher in Authentik über Bindings auf eine Gruppe beschränken und die E-Mail des lokalen Admin-Accounts vorab auf die Authentik-Adresse setzen.

E-Mail-Versand

Unter Admin → SMTP den Provider Other wählen. Das Feld „Reply address“ ist zugleich die Absenderadresse. Port 465 wird mit direkter Verschlüsselung, alle anderen Ports mit STARTTLS genutzt. Beispiel Proton Mail (nur bezahlte Tarife mit eigener Domain): Host smtp.protonmail.ch, Port 587, Benutzer und Passwort aus einem SMTP-Token.

---

Welcome to Peppermint Ticket Management 🍵

This project is supported by:

Ticket Management System in order to help helpdesks & service desks manage internal staff & customer requests

✨ Features

• Ticket Creation: Bog standard ticket creation with a markdown editor and file uploads
• A log of client history
• Markdown based Notebook with todo lists
• Responsive: Designed for variable screen sizes from mobile up to 4k
• Multi-deployment: Quickly deploy using docker & pm2
• Simple to Use: Designed to be easy to use with a simple logical workflow

🐳 Installation with docker

Check out the getting started guide if this is the first time you've used Peppermint:

version: "3.1"

services:
  peppermint_postgres:
    container_name: peppermint_postgres
    image: postgres:latest
    restart: always
    ports:
      - 5432:5432
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: peppermint
      POSTGRES_PASSWORD: 1234
      POSTGRES_DB: peppermint

  peppermint:
    container_name: peppermint
    image: pepperlabs/peppermint:latest
    ports:
      - 3000:3000
      - 5003:5003
    restart: always
    depends_on:
      - peppermint_postgres
    environment:
      DB_USERNAME: "peppermint"
      DB_PASSWORD: "1234"
      DB_HOST: "peppermint_postgres"
      SECRET: 'peppermint4life'

volumes:
 pgdata:

Once this is completed then you can go to your server-ip:3000 which was added to the compose file and login.

The default login credentials are

admin@admin.com
1234

One click installers

• We are now on linode marketplace we can be viewed here here
• We have a one line installer for Ubuntu and Debian (for the moment) and can be viewed here here

Documentation

We have started working on creating documentation for peppermint which covers development to general usage. Click here to be taken directly there.

Motivation

• This was initially a project to tie together my react and nodeJS skills and show something for my portfolio
• It looked terrible! But it worked and showed functionaility, which got me a job.
• Learn and deploy with docker
• Redo the UI, completly from the ground up. Which has now been completed and for me looks great.
• Build on this foundation and create a fully fledged product which offers what the big boys offer, but, at a much better ROI than signing up for zendesk etc.

Give a ⭐️ if this project helped you!

Star History

Activity

• Website: peppermint.sh
• Github: @potts99
• LinkedIn: @jack-andrews-146852131