3.1.0

Author: Ralex91

.dockerignore

@@ -1,3 +1,20 @@
 **/node_modules
 .pnpm-store
 .git
+
+# gitignored / secrets - must never enter the build context
+config
+.env
+.secrets
+release.json
+
+# not needed to build, keeps context small and cache stable
+.github
+.vscode
+docs
+*.md
+event.json
+compose.yml
+.prettierignore
+.prettierrc.json
+oxlint.config.ts

.github/workflows/ci.yml

@@ -7,13 +7,13 @@ jobs:
   checks:
     name: Lint & Format
     runs-on: ubuntu-latest
-    if: github.actor != 'dependabot[bot]'
+    if: github.actor != 'dependabot[bot]' || contains(github.event.pull_request.labels.*.name, 'javascript')
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
         with:
           version: 11
 

.github/workflows/docker-release.yml

@@ -16,7 +16,7 @@ jobs:
       packages: write
     steps:
       - name: Checkout code
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Extract version and tags
         run: |
@@ -35,6 +35,9 @@ jobs:
       - name: Extract repository name (lowercase)
         run: echo "REPO_NAME=$(basename ${{ github.repository }} | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
 
+      - name: Extract full repository path (lowercase, for GHCR)
+        run: echo "GHCR_REPO=$(echo ${{ github.repository }} | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3 # v4.1.0
         with:
@@ -54,6 +57,14 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      - name: Log in to GitHub Container Registry
+        if: ${{ !env.ACT }}
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Build and push
         uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
@@ -64,6 +75,9 @@ jobs:
             ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.REPO_NAME }}:${{ env.VERSION }}
             ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.REPO_NAME }}:${{ env.MAJOR_MINOR }}
             ${{ secrets.DOCKERHUB_USERNAME }}/${{ env.REPO_NAME }}:latest
+            ghcr.io/${{ env.GHCR_REPO }}:${{ env.VERSION }}
+            ghcr.io/${{ env.GHCR_REPO }}:${{ env.MAJOR_MINOR }}
+            ghcr.io/${{ env.GHCR_REPO }}:latest
           cache-from: type=gha
           cache-to: type=gha,mode=max
           build-args: |

.prettierignore

@@ -0,0 +1,7 @@
+/config
+
+**/node_modules
+**/dist
+**/route.gen.ts
+pnpm-lock.yaml
+

Dockerfile

@@ -1,5 +1,5 @@
 # ---- BASE ----
-FROM node:25-alpine AS base
+FROM node:26-alpine AS base
 RUN npm install -g pnpm
 
 # ---- BUILDER ----
@@ -18,7 +18,7 @@ COPY . .
 RUN pnpm build
 
 # ---- RUNNER ----
-FROM alpine:3.23.4 AS runner
+FROM alpine:3.24.1 AS runner
 
 RUN apk add --no-cache nginx nodejs supervisor
 

README.md

@@ -25,7 +25,7 @@ Choose one of the following deployment methods:
 
 ### Without Docker
 
-- Node.js : version 22 or higher
+- Node.js : version 24 or higher
 - PNPM : version 10.16 or higher (learn more [here](https://pnpm.io/))
 
 ### With Docker
@@ -55,6 +55,15 @@ docker run -d \
   ralex91/razzia:latest
 ```
 
+The image is also published on the GitHub Container Registry, if you prefer using it instead of Docker Hub:
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -v ./config:/app/config \
+  ghcr.io/ralex91/razzia:latest
+```
+
 **Configuration Volume:**
 The `-v ./config:/app/config` option mounts a local `config` folder to persist your game settings and quizzes. This allows you to:
 
@@ -85,87 +94,34 @@ pnpm install
 
 ```bash
 # Development mode
-pnpm run dev
+pnpm dev
 
 # Production mode
-pnpm run build
+pnpm build
 pnpm start
 ```
 
 ## ⚙️ Configuration
 
-The configuration is split into two main parts:
-
-### 1. Game Configuration (`config/game.json`)
-
-Main game settings:
+**⚠️ Required:** set a manager password in `config/game.json` before going live.
 
 ```json
 {
   "managerPassword": "PASSWORD"
 }
 ```
 
-Options:
-
-- `managerPassword`: The master password for accessing the manager interface. **Must be changed from the default `"PASSWORD"` value**, otherwise manager access is blocked.
+`managerPassword` **must be changed** from the default `"PASSWORD"` value, otherwise manager access is blocked.
 
-### 2. Quiz Configuration (`config/quizz/*.json`)
-
-Quizzes can be created in two ways:
-
-- **Via the Quiz Editor** — use the built-in editor available in the manager dashboard (recommended)
-- **Via JSON files** — manually create files in the `config/quizz/` directory
-
-You can have multiple quiz files and select which one to use when starting a game.
-
-Example quiz configuration (`config/quizz/example.json`):
-
-```json
-{
-  "subject": "Example Quiz",
-  "questions": [
-    {
-      "question": "What is the correct answer?",
-      "answers": ["No", "Yes", "No", "No"],
-      "solutions": [1],
-      "cooldown": 5,
-      "time": 15
-    },
-    {
-      "question": "Which of these are primary colors?",
-      "answers": ["Red", "Green", "Blue", "Yellow"],
-      "solutions": [0, 2, 3],
-      "cooldown": 5,
-      "time": 20
-    },
-    {
-      "question": "What is the correct answer with an image?",
-      "answers": ["No", "Yes", "No", "No"],
-      "media": {
-        "type": "image",
-        "url": "https://placehold.co/600x400.png"
-      },
-      "solutions": [1],
-      "cooldown": 5,
-      "time": 20
-    }
-  ]
-}
-```
+## 📚 Documentation
 
-Quiz Options:
+- [Configuration](docs/configuration.md): manager password, via the `config` folder.
+- [Quiz](docs/quiz.md): creating and structuring quizzes.
+- [Branding](docs/branding.md): optional custom theming.
+- [Reverse Proxy](docs/reverse-proxy.md): running behind Traefik, Nginx, Caddy, or another reverse proxy.
+- [WebSocket Protocol](docs/websocket-protocol.md): build a custom client (e.g. an ESP32 physical buzzer).
 
-- `subject`: Title/topic of the quiz
-- `questions`: Array of question objects containing:
-  - `question`: The question text
-  - `answers`: Array of possible answers (2-4 options)
-  - `media`: Optional media object displayed with the question:
-    - `type`: `"image"`, `"video"`, or `"audio"`
-    - `url`: URL of the media
-  - `solutions`: Array of correct answer indices (0-based). Use multiple indices for multi-answer questions
-  - `cooldown`: Time in seconds before answers are revealed (3-15)
-  - `time`: Time in seconds allowed to answer (5-120)
+Full index in [docs/](docs/README.md).
 
 ## 🎮 How to Play
 
@@ -183,4 +139,4 @@ For bug reports or feature requests, please [create an issue](https://github.com
 
 ## ⭐ Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=Ralex91/Razzia&type=date&legend=bottom-right)](https://www.star-history.com/#Ralex91/Razzia&type=date&legend=bottom-right)
+[![Star History Chart](https://api.star-history.com/svg?repos=Ralex91/Razzia&type=date&logscale=&legend=bottom-right)](https://www.star-history.com/#Ralex91/Razzia&type=date&logscale=&legend=bottom-right)

docker/nginx.conf

@@ -8,6 +8,10 @@ server {
         try_files $uri $uri/ /index.html;
     }
 
+    location /branding/ {
+        alias /app/config/branding/;
+    }
+
     location /ws {
         proxy_pass http://127.0.0.1:3001;
         proxy_http_version 1.1;

docs/README.md

@@ -0,0 +1,11 @@
+# 📚 Documentation
+
+This folder covers the basic setup (config, quizzes, branding) as well as more advanced usage, like running behind a reverse proxy or building your own client.
+
+- [Configuration](configuration.md): manager password, via the `config` folder.
+- [Quiz](quiz.md): creating and structuring quizzes via `config/quizz/*.json`.
+- [Branding](branding.md): optional custom theming via `config/branding/`.
+- [Reverse Proxy](reverse-proxy.md): running Razzia behind Traefik, Nginx, Caddy, or another reverse proxy.
+- [WebSocket Protocol](websocket-protocol.md): the player-facing event protocol, for building custom clients (e.g. a physical buzzer).
+
+Back to the [main README](../README.md).

docs/branding.md

@@ -0,0 +1,30 @@
+# Custom Branding
+
+Optional, lives in `config/branding/` (alongside `config/game.json`, see [Configuration](configuration.md)).
+
+You can fully rebrand the app **without touching the code** by dropping files into a `config/branding/` folder. If it is absent, the default look is used.
+
+Create `config/branding/theme.json`:
+
+```json
+{
+  "appName": "My Quiz",
+  "colors": { "primary": "#ff9900", "secondary": "#1a140b" },
+  "answerColors": ["#e69f00", "#56b4e9", "#3dbfa0", "#cc79a7"],
+  "font": {
+    "family": "Rubik",
+    "url": "https://fonts.googleapis.com/css2?family=Rubik:wght@300..900&display=swap"
+  },
+  "logo": "/branding/logo.svg",
+  "favicon": "/branding/favicon.svg",
+  "background": "/branding/background.png"
+}
+```
+
+All fields are optional: anything you omit keeps its default value.
+
+- `appName`: app name + browser tab title
+- `colors`: CSS color tokens (at least `primary` and `secondary`)
+- `answerColors`: up to 4 answer-button colors
+- `font`: a font family + an optional stylesheet URL (e.g. Google Fonts)
+- `logo` / `favicon` / `background`: drop the files in `config/branding/` and reference them here

docs/configuration.md

@@ -0,0 +1,19 @@
+# Configuration
+
+The configuration lives in the `config` folder (mounted as a Docker volume, or `../../config` relative to the packages when running without Docker).
+
+## Game Configuration (`config/game.json`)
+
+Main game settings:
+
+```json
+{
+  "managerPassword": "PASSWORD"
+}
+```
+
+Options:
+
+- `managerPassword`: The master password for accessing the manager interface. **Must be changed from the default `"PASSWORD"` value**, otherwise manager access is blocked.
+
+See also: [Quiz Configuration](quiz.md) and [Custom Branding](branding.md), also stored in the `config` folder.