Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,19 @@ data/dashboard-settings.json
data/update-notice.json
data/dashboard-favicon.*

# Customer files. Own panel images and own locale texts live outside the tracked
# files, so a customer change never blocks `git pull`. The shipped default logo
# is in assets/default/; the other tracked files under assets/ are re-included.
/assets/*
!/assets/README.md
!/assets/msk-ticket-bot-banner.png
!/assets/bot-hosting-*.png
!/assets/default/
/locales/custom/
/locales/*.bak
/locales/*.pre-custom-layer
/.update-stash/

# Config (contains IDs/tokens)
config/config.jsonc
config/snippets.jsonc
35 changes: 35 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **Own texts live in `locales/custom/`.** Changes to the bot's texts are kept
in `locales/custom/<lang>.json` (ignored by git), which holds only the texts
that differ from the shipped `locales/<lang>.json`. On start the bot lays
that file over the shipped one, so the customer's texts win and new texts
from an update still arrive. A broken custom file only logs a warning. The
dashboard's locale editor still shows the whole file, but saves only the
difference and never writes the shipped file again. A new **Reset to
default** button (`DELETE /api/locales/:name`, permission `config.edit`,
audited as `locale.reset`) drops the custom texts of a file.
- **`npm run update`** runs the same update routine as the dashboard's Update
button, without the dashboard, for self-hosters and for updating many
installations in a loop. It does not restart the bot.

### Changed

- **Updating no longer fails because of local changes to the lockfile, the
texts or the logo.** The update routine (dashboard button and
`npm run update`) resets `package-lock.json` before and after
`npm install`, moves edits made directly in `locales/<lang>.json` into
`locales/custom/` once (the edited file is kept as
`locales/<lang>.json.pre-custom-layer`), sets a replaced `assets/logo.png`
aside and puts it back after the pull. It pulls with `git pull --ff-only`
and puts set-aside files back when the pull fails. This migration runs
automatically, nothing needs to be done by hand.
- **The default panel logo lives in `assets/default/logo.png`.** Panel images
are looked up in `assets/` first and in `assets/default/` second, so
`panel.logo.file: "logo.png"` keeps working with or without an own logo.
Images added to `assets/` are ignored by git. `assets/logo.png` is still
shipped in this version and will be removed from the repository in a later
one; an own `assets/logo.png` keeps working either way.
- After updating to this version, restart the dashboard service once (not only
the bot), so the web server loads the new update routine and locale routes.

### Fixed

- The startup log printed `API key valid → business` in lower case, because
Expand Down
15 changes: 13 additions & 2 deletions assets/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,15 @@
Place your panel banner image here.
# Panel images

Put your own panel images here, for example `logo.png` or `banner.png`.
Supported formats: PNG, JPG, GIF, WEBP

Configure it in `config/config.jsonc`:
The bot looks for the file named in the config in this folder first and then in
`default/`, which holds the MSK logo. So `"file": "logo.png"` shows the MSK logo
until you put your own `logo.png` here. Images you add here are ignored by git,
and the update routine (`npm run update` or the dashboard's Update button) sets a
replaced `logo.png` aside and puts it back, so your images never block an update.

Configure them in `config/config.jsonc`:
```json
"panel": {
"logo": {
Expand All @@ -14,3 +22,6 @@ Configure it in `config/config.jsonc`:
}
},
```

The other images in this folder (`msk-ticket-bot-banner.png`, `bot-hosting-*.png`)
belong to the documentation.
Binary file added assets/default/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 17 additions & 1 deletion docs/configuration-de.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Ein Syntaxfehler wird mit Zeile, Spalte und einem Zeiger auf die Stelle gemeldet
| `transcriptDesign` | `modern` (Standard) oder `classic` |
| `transcriptLang` | Sprache des Transkripts, dieselben Codes wie `lang`, Rückfall auf Englisch |
| `openTicketChannelId` | Kanal, in den `/setup` das Panel postet |
| `panel` | `interactionType` (`BUTTON` oder `SELECT_MENU`), `autoUpdateOnStart`, `logo`, `banner` (Dateien aus `assets/`) |
| `panel` | `interactionType` (`BUTTON` oder `SELECT_MENU`), `autoUpdateOnStart`, `logo`, `banner` (Dateien aus `assets/`, siehe [Panel-Bilder](#panel-bilder)) |
| `ticketTypes` | Bis zu 25 Ticket-Typen, siehe unten |
| `ticketNameOption` | Vorlage für den Kanalnamen: `USERNAME`, `USERID`, `TICKETCOUNT` |
| `claimOption` | `claimButton`, `nameWhenClaimed`, `categoryWhenClaimed` |
Expand Down Expand Up @@ -118,6 +118,22 @@ Platzhalter: `{user}`, `{staff}`, `{type}`, `{priority}`. Befehle: `/snippet sen

Tokens, der MSK-API-Key, Datenbank-Zugangsdaten und Dashboard-Secrets gehören in die `.env`, nie in die `config.jsonc`. Siehe [Installation](installation-de.md) und [Dashboard](dashboard-de.md).

## Panel-Bilder

`panel.logo.file` und `panel.banner.file` nennen eine Datei in `assets/`. Dein eigenes Logo oder Banner legst du dort ab, etwa als `assets/logo.png` oder `assets/banner.png`. Liegt die Datei nicht in `assets/`, sucht der Bot in `assets/default/`. Dort liegt das MSK-Logo, `"file": "logo.png"` zeigt also das MSK-Logo, bis du ein eigenes ablegst. Bilder, die du in `assets/` ablegst, ignoriert git, und die Update-Routine legt ein ersetztes `assets/logo.png` beiseite und stellt es danach zurück. Deine Bilder blockieren also kein Update.

## Texte anpassen

Einen Text des Bots änderst du im Dashboard (Konfiguration, Reiter der Locale-Datei) oder trägst ihn selbst in `locales/custom/<lang>.json` ein. Diese Datei enthält nur die Texte, die du änderst, im selben Aufbau wie `locales/<lang>.json`:

```json
{ "buttons": { "openTicket": "Support kontaktieren" } }
```

Beim Start liest der Bot `locales/<lang>.json` und legt deine Datei darüber. Deine Texte gewinnen, alles andere kommt aus der mitgelieferten Datei, neue Texte aus einem Update erscheinen also von selbst. `locales/<lang>.json` selbst bitte nicht bearbeiten, ein Update ersetzt sie. `locales/custom/` ignoriert git. Eine fehlerhafte eigene Datei erzeugt nur eine Warnung im Log, der Bot nimmt dann die mitgelieferten Texte.

Texte, die mit einer älteren Version in `locales/<lang>.json` geändert wurden, wandern beim nächsten `npm run update` oder Update aus dem Dashboard von selbst nach `locales/custom/`. Die bearbeitete Datei bleibt als `locales/<lang>.json.pre-custom-layer` erhalten.

## Eine Sprache hinzufügen

1. `locales/en.json` nach `locales/<code>.json` kopieren, etwa `locales/it.json`.
Expand Down
18 changes: 17 additions & 1 deletion docs/configuration-en.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ A syntax error is reported with line, column and a pointer to the spot. Placehol
| `transcriptDesign` | `modern` (default) or `classic` |
| `transcriptLang` | Language of the transcript, same codes as `lang`, falls back to English |
| `openTicketChannelId` | Channel that `/setup` posts the panel to |
| `panel` | `interactionType` (`BUTTON` or `SELECT_MENU`), `autoUpdateOnStart`, `logo`, `banner` (files from `assets/`) |
| `panel` | `interactionType` (`BUTTON` or `SELECT_MENU`), `autoUpdateOnStart`, `logo`, `banner` (files from `assets/`, see [Panel images](#panel-images)) |
| `ticketTypes` | Up to 25 ticket types, see below |
| `ticketNameOption` | Channel name template: `USERNAME`, `USERID`, `TICKETCOUNT` |
| `claimOption` | `claimButton`, `nameWhenClaimed`, `categoryWhenClaimed` |
Expand Down Expand Up @@ -118,6 +118,22 @@ Placeholders: `{user}`, `{staff}`, `{type}`, `{priority}`. Commands: `/snippet s

Tokens, the MSK API key, database credentials and dashboard secrets go into `.env`, never into `config.jsonc`. See [Installation](installation-en.md) and [Dashboard](dashboard-en.md).

## Panel images

`panel.logo.file` and `panel.banner.file` name a file in `assets/`. Put your own logo or banner there, for example `assets/logo.png` or `assets/banner.png`. When the file is not in `assets/`, the bot looks in `assets/default/`, which holds the MSK logo, so `"file": "logo.png"` shows the MSK logo until you add your own. Images you add to `assets/` are ignored by git, and the update routine sets a replaced `assets/logo.png` aside and puts it back, so your images never block an update.

## Changing texts

Change a bot text in the dashboard (Configuration, tab of the locale file) or write it into `locales/custom/<lang>.json` yourself. That file holds only the texts you change, in the same structure as `locales/<lang>.json`:

```json
{ "buttons": { "openTicket": "Contact support" } }
```

On start the bot reads `locales/<lang>.json` and lays your file over it. Your texts win, everything else comes from the shipped file, so new texts from an update show up on their own. Do not edit `locales/<lang>.json` itself, an update replaces it. `locales/custom/` is ignored by git. A broken custom file only logs a warning, and the bot then uses the shipped texts.

Texts changed in `locales/<lang>.json` with an older version move to `locales/custom/` on their own with the next `npm run update` or dashboard update. The edited file is kept as `locales/<lang>.json.pre-custom-layer`.

## Adding a language

1. Copy `locales/en.json` to `locales/<code>.json`, for example `locales/it.json`.
Expand Down
11 changes: 9 additions & 2 deletions docs/dashboard-de.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ aktivierst, ändert sich an deinem Bot nichts.
| **Meine Tickets** | Jedes Mitglied sieht die selbst geöffneten Tickets und kann in offenen antworten. Die Antwort erscheint im Discord-Kanal unter dem eigenen Namen. Geschlossene Tickets bieten einen Transcript-Download und, mit Premium, einen "Transcript öffnen"-Link. |
| **Tickets** | Vollständige Liste mit Filtern, Ticket-Detail mit dem Live-Verlauf, Claim / Schließen / Wieder öffnen / Verschieben / Sperren / Priorität. |
| **Statistiken** | Gesamtzahlen, Durchschnittsbewertung, durchschnittliche Bearbeitungszeit und ein Team-Ranking nach geschlossenen Tickets. |
| **Konfiguration** | Bearbeite `config.jsonc`, `snippets.jsonc`, `.env` und die Locale-Dateien wahlweise in einer strukturierten **Formular**-Ansicht oder einer rohen **Datei**-Ansicht (mit Zeilennummern und Syntax-Highlighting). Formular-Änderungen erhalten die `//`-Kommentare, und ein Seitenpanel löst Discord-Rollen-/Kanal-/Kategorie-**Namen** auf, sodass du nie nach rohen IDs suchen musst. |
| **Bot-Steuerung** | Starten, stoppen, neu starten und aktualisieren des Bots, plus eine Live-Konsole. |
| **Konfiguration** | Bearbeite `config.jsonc`, `snippets.jsonc`, `.env` und die Locale-Dateien wahlweise in einer strukturierten **Formular**-Ansicht oder einer rohen **Datei**-Ansicht (mit Zeilennummern und Syntax-Highlighting). Formular-Änderungen erhalten die `//`-Kommentare, und ein Seitenpanel löst Discord-Rollen-/Kanal-/Kategorie-**Namen** auf, sodass du nie nach rohen IDs suchen musst. Änderungen an einer Locale-Datei landen als Unterschied zu den mitgelieferten Texten in `locales/custom/`, Updates behalten sie also; **Auf Standard zurücksetzen** entfernt sie wieder (siehe [Texte anpassen](configuration-de.md#texte-anpassen)). |
| **Bot-Steuerung** | Starten, stoppen, neu starten und aktualisieren des Bots, plus eine Live-Konsole. **Update** führt dieselbe Routine aus wie `npm run update` (siehe [Aktualisieren](installation-de.md#aktualisieren)). |
| **Berechtigungen** | Lege fest, welche Rollen und Nutzer das Dashboard verwenden dürfen und was sie tun dürfen. |
| **Dashboard-Einstellungen** | Akzentfarbe und Favicon, abgesichert über eigene Ansehen-/Bearbeiten-Rechte. Die Akzentfarbe wird an die helle und die dunkle Darstellung angepasst. |
| **Sprache** | Jeder Nutzer wählt seine eigene Oberflächensprache aus sieben Übersetzungen. |
Expand Down Expand Up @@ -298,6 +298,13 @@ NSSM-/PM2-Dienst neu, unter dem du `dashboard.js` laufen lässt). Reine
Bot-Änderungen (Commands, Events, Datenbank) greifen dagegen schon über den
Update-Button.

**Das Update scheitert mit "git pull failed"**
Das Update zieht nur als Fast-Forward. Deine eigenen Texte, Bilder und die
Lockfile erledigt es selbst, meist steckt also ein lokaler Commit oder eine
Änderung an einer anderen versionierten Datei dahinter, etwa am Code. Sieh mit
`git status` im Bot-Ordner nach oder starte `npm run update` im Terminal, dann
siehst du die ganze Ausgabe.

**Das Dashboard verweigert den Start mit dem Hinweis, die Konfiguration sei nicht sicher**
Du hast das Dashboard ohne HTTPS an eine öffentliche Schnittstelle gebunden. Geh
entweder zurück auf `DASHBOARD_HOST=127.0.0.1` und nutze einen Reverse-Proxy oder
Expand Down
10 changes: 8 additions & 2 deletions docs/dashboard-en.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ nothing about your bot changes.
| **My tickets** | Every member sees the tickets they opened and can reply to the open ones. Their reply is posted in the Discord channel under their own name. Closed tickets offer a transcript download and, on premium, an "Open transcript" link. |
| **Tickets** | Full list with filters, ticket detail with the live conversation, claim / close / reopen / move / lock / priority. |
| **Statistics** | Totals, average rating, average handling time, and a team ranking by tickets closed. |
| **Configuration** | Edit `config.jsonc`, `snippets.jsonc`, `.env` and the locale files in either a structured **form** view or a raw **file** view (with line numbers and syntax highlighting). Form edits preserve the `//` comments, and a side panel resolves Discord role/channel/category **names** so you never have to hunt for raw IDs. |
| **Bot control** | Start, stop, restart and update the bot, plus a live console. |
| **Configuration** | Edit `config.jsonc`, `snippets.jsonc`, `.env` and the locale files in either a structured **form** view or a raw **file** view (with line numbers and syntax highlighting). Form edits preserve the `//` comments, and a side panel resolves Discord role/channel/category **names** so you never have to hunt for raw IDs. Changes to a locale file are stored in `locales/custom/` as the difference to the shipped texts, so updates keep them; **Reset to default** removes them again (see [Changing texts](configuration-en.md#changing-texts)). |
| **Bot control** | Start, stop, restart and update the bot, plus a live console. **Update** runs the same routine as `npm run update` (see [Updating](installation-en.md#updating)). |
| **Permissions** | Decide which roles and users may use the dashboard, and what they may do. |
| **Dashboard settings** | Accent colour and favicon, gated by their own view / edit permissions. The accent is fitted to the light and the dark theme. |
| **Language** | Each user picks their own interface language from seven translations. |
Expand Down Expand Up @@ -284,6 +284,12 @@ answers 404. Restart the service once so the web server reloads:
`dashboard.js` under). Plain bot changes (commands, events, the database) do take
effect through the Update button.

**Update fails with "git pull failed"**
The update only pulls as a fast-forward. Your own texts, images and the
lockfile are handled for you, so this usually means a local commit or a change
to another tracked file, such as code. Run `git status` in the bot folder, or
run `npm run update` in a terminal to see the full output.

**The dashboard refuses to start, saying the configuration is not safe**
You bound the dashboard to a public interface without HTTPS. Either go back to
`DASHBOARD_HOST=127.0.0.1` and use a reverse proxy, or set `DASHBOARD_PUBLIC_URL`
Expand Down
6 changes: 5 additions & 1 deletion docs/installation-de.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,12 @@ Den Node-Pfad mit `which node` prüfen und `ExecStart` in der Unit anpassen, fal
Der Bot prüft beim Start auf neue Releases und meldet sie im Log-Kanal (`updateNotification` in der Config).

```bash
git pull && npm install
npm run update
sudo systemctl restart ticketbot
```

`npm run update` ist dieselbe Routine wie der Button **Update** im Dashboard. Vor dem Pull stellt sie die mitgelieferte `package-lock.json` wieder her (npm schreibt sie bei jeder Installation um), verschiebt Texte, die du direkt in `locales/<lang>.json` geändert hast, nach `locales/custom/` und legt ein ersetztes `assets/logo.png` beiseite. Danach laufen `git pull --ff-only` und `npm install --omit=dev`, und dein Logo kommt zurück. Deine eigenen Texte und Bilder bleiben erhalten und lassen das Update nicht mehr scheitern. Der Befehl startet den Bot nicht neu, das machst du so, wie der Bot bei dir läuft (systemd, PM2, Dashboard). Läuft bei dir das Dashboard, starte dessen Dienst neu und nicht nur den Bot, damit auch der Webserver die neue Version lädt.

Wer von 2.22.0 oder älter kommt, hat `npm run update` noch nicht und aktualisiert einmal von Hand: `git checkout -- package-lock.json && git pull && npm install --omit=dev`.

Mit Docker: `docker compose pull && docker compose up -d`. Vorher den [CHANGELOG](../CHANGELOG.md) für alle übersprungenen Versionen lesen, besonders Einträge mit **Breaking**. Datenbank-Migrationen laufen beim nächsten Start automatisch.
6 changes: 5 additions & 1 deletion docs/installation-en.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,8 +92,12 @@ Check the Node path with `which node` and adjust `ExecStart` in the unit if it i
The bot checks for new releases on start and posts them to the log channel (`updateNotification` in the config).

```bash
git pull && npm install
npm run update
sudo systemctl restart ticketbot
```

`npm run update` is the same routine as the **Update** button in the dashboard. Before it pulls, it puts back the shipped `package-lock.json` (npm rewrites it on every install), moves texts you changed directly in `locales/<lang>.json` into `locales/custom/` and sets a replaced `assets/logo.png` aside. Then it runs `git pull --ff-only` and `npm install --omit=dev` and puts your logo back. Your own texts and images are kept, and they no longer make the update fail. The command does not restart the bot, so restart it the way you run it (systemd, PM2, the dashboard). If you run the dashboard, restart its service rather than only the bot, so the web server loads the new version too.

Coming from 2.22.0 or older, where `npm run update` does not exist yet, update once by hand: `git checkout -- package-lock.json && git pull && npm install --omit=dev`.

With Docker: `docker compose pull && docker compose up -d`. Read the [CHANGELOG](../CHANGELOG.md) for the versions you skip, especially entries marked **Breaking**. Database migrations run automatically on the next start.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
"dashboard": "node dashboard.js",
"dashboard:setup": "node scripts/dashboard-setup.js",
"db:migrate": "node scripts/migrate-db.js",
"update": "node scripts/update.js",
"test": "node --test \"tests/**/*.test.js\""
},
"engines": {
Expand Down
36 changes: 36 additions & 0 deletions scripts/update.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
#!/usr/bin/env node
/**
* `npm run update`: the same update routine as the dashboard's Update button,
* without the dashboard. Meant for self-hosters and for updating many hosted
* installations in a loop.
*
* It resets package-lock.json, moves locale edits from the tracked
* locales/<lang>.json into locales/custom/ (one-time migration), sets a replaced
* assets/logo.png aside and puts it back, then runs `git pull --ff-only` and
* `npm install --omit=dev`. It does not restart the bot: do that the way the bot
* runs (systemd, PM2, the dashboard).
*
* Exit code 0 on success, 1 on failure.
*/

const path = require('path');
const { runUpdate } = require('../src/utils/updater');

const ROOT = path.resolve(__dirname, '..');
const log = (text) => {
const s = String(text);
process.stdout.write(s.endsWith('\n') ? s : `${s}\n`);
};

runUpdate({ root: ROOT, log })
.then((result) => {
if (!result.ok) {
process.stderr.write(`\nUpdate failed: ${result.error}\n${result.detail ? `${result.detail}\n` : ''}`);
process.exit(1);
}
log('\nUpdate finished. Restart the bot to load the new version.');
})
.catch((err) => {
process.stderr.write(`\nUpdate failed: ${err.stack || err.message}\n`);
process.exit(1);
});
Loading
Loading