No description
  • Go 50.2%
  • TypeScript 31.7%
  • C 11.9%
  • C++ 4.7%
  • HTML 1%
  • Other 0.5%
Find a file
Jonas Leder d406722569
All checks were successful
ci / server-binary (amd64, linux) (push) Successful in 2m19s
ci / bridge-binary (amd64, windows) (push) Successful in 1m17s
ci / build-1 (push) Successful in 3m26s
ci / bridge-binary (arm64, darwin) (push) Successful in 1m23s
ci / server-binary (arm64, darwin) (push) Successful in 2m29s
ci / server-binary (arm64, linux) (push) Successful in 2m29s
ci / bridge-binary (arm64, linux) (push) Successful in 1m44s
ci / build (push) Successful in 5m25s
ci / chart (push) Successful in 0s
ci / backend-docker (push) Successful in 0s
ci / build-3 (push) Successful in 1m0s
ci / pages (push) Successful in 3m57s
ci / frontend-build (push) Successful in 44s
ci / frontend-tests (push) Successful in 51s
ci / bridge-tests (push) Successful in 52s
ci / backend-tests (push) Successful in 2m21s
ci / build-2 (push) Successful in 2m48s
ci / bridge-docker (push) Successful in 0s
ci / bridge-binary (amd64, linux) (push) Successful in 1m9s
ci / server-binary (amd64, windows) (push) Successful in 1m58s
ci / frontend-docker (push) Successful in 0s
pages: kill docs server by pid
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 15:47:39 +01:00
.claude add graphify report 2026-06-15 17:40:28 +02:00
.forgejo/workflows pages: kill docs server by pid 2026-11-18 15:47:39 +01:00
.vscode auto update rebooted tags 2026-10-03 16:07:51 +02:00
backend Update module golang.org/x/oauth2 to v0.38.0 2026-11-17 20:56:40 +00:00
bridge auto update rebooted tags 2026-10-03 16:07:51 +02:00
container add security headers 2026-11-12 17:28:00 +01:00
documentation Publish user docs to git-pages 2026-11-18 15:26:11 +01:00
filamentmanagement-display update boards 2026-10-03 16:08:58 +02:00
frontend Publish user docs to git-pages 2026-11-18 15:26:11 +01:00
graphify-out fix frontend build 2026-11-17 21:31:27 +01:00
helm Port CI to Forgejo Actions 2026-11-18 10:12:23 +01:00
.gitignore ignore chart artifacts in git 2026-10-10 20:22:14 +02:00
.gitmodules implement touch display based on esp32 2026-08-15 18:15:45 +02:00
CLAUDE.md Publish user docs to git-pages 2026-11-18 15:26:11 +01:00
compose.yaml Update redis Docker tag to v8 2026-10-03 22:33:13 +00:00
Dockerfile.backend Update golang Docker tag to v1.27.4 2026-11-13 23:18:35 +00:00
Dockerfile.bridge Update golang Docker tag to v1.27.4 2026-11-13 23:18:35 +00:00
Dockerfile.frontend Update cgr.dev/chainguard/nginx Docker digest to b05ccf9 2026-11-18 13:20:50 +00:00
README.md Publish user docs to git-pages 2026-11-18 15:26:11 +01:00
renovate.json enable automerge 2026-08-28 21:49:36 +02:00

Filament Management

A web app for managing filament spools, vendors, and inventory with a Go backend and a React + MUI frontend.

📖 User documentation

Features

  • Vendors, filaments, and spools management with inline tables and filters
  • RFID tracking and per-spool weight tracking (set, reduce, measure with spool)
  • SpoolmanDB import for vendors and filaments
  • Spoolman server import via CLI
  • Admin settings for session timeout, SpoolmanDB URL, and OpenID Connect
  • Mobile-friendly UI with material design and dark mode

Architecture

  • Backend: Go, Gin, Gorm, SQLite/MySQL
  • Frontend: React, MUI, Vite (pnpm)
  • API base path: /api/v1

Quick Start

Backend

cd backend
# Optional: set environment variables (see below)
go run .

Frontend

cd frontend
pnpm install
pnpm dev

The frontend proxies requests to the backend under /api/.

Configuration

Environment variables (backend)

  • DB_DRIVER: sqlite (default) or mysql
  • DB_NAME: SQLite file name or MySQL database name
  • DB_USER: MySQL user
  • DB_PASSWORD: MySQL password
  • DB_HOST: MySQL host
  • DB_PORT: MySQL port (default 3306)
  • EXECUTE_MIGRATIONS: true (default) to run migrations on startup. Set to false when running them separately with the migrate command (the Helm chart does this in a hook Job)

Admin settings

Open Settings in the UI (admin only):

  • Session timeout (minutes): how long sessions are valid
  • SpoolmanDB URL: source for the built-in SpoolmanDB import
  • OpenID Connect:
    • Issuer URL
    • Client ID
    • Client Secret
    • Enable OpenID login
    • Auto-redirect to provider
  • Sentry:
    • Backend DSN (applied after backend restart)
    • Frontend DSN
    • Environment (release is set automatically in CI, -1 in dev)
    • Traces sample rate (0.0-1.0, optional)

Use the Well-known configuration URL field to load OpenID metadata and auto-fill the issuer. The redirect URL is auto-generated as https://<host>/api/v1/oidc/callback (shown in Settings for copy/paste into your provider).

To bypass auto-redirect and show the local login screen, open the UI with ?local=1 (for example: /#/?local=1).

CLI Commands

Create a user

cd backend
go run . create-user --username admin --password change-me --name "Admin" --admin

Docker:

docker compose run --rm backend create-user --username admin --password change-me --name "Admin" --admin

Import from Spoolman server

cd backend
go run . import-spoolman --url http://spoolman.local:7912

Docker:

docker compose run --rm backend import-spoolman --url http://spoolman.local:7912

Options:

  • --skip-existing (default: true): skip vendors/filaments that already exist
  • --dry-run: do not write to the database, only report changes

OpenID Connect Flow

  • /api/v1/oidc/login redirects to the provider
  • /api/v1/oidc/callback creates the user on first login and issues a session cookie
  • /api/v1/oidc/config exposes login settings for the frontend

API Docs

Swagger docs are available at /api/docs/ when the backend is running.

Helm

A Helm chart is available in helm/ for deploying the app.

Production Deployment

Recommendet is the Kubernetes method using helm and a propper ingress. When using the docker based setup you're responsible to correctly configure the reverse proxy to router / to the frontend and /api to the backend

Kubernetes

On each master build and tag the chart is pushed to the Forgejo OCI registry: helm install filamentmanagement oci://forgejo.jonasled.dev/jonasled/filamentmanagement/charts/filamentmanagement --version <version> For the Helm values check the helm/values.yaml file.

Docker

For a docker based setup download the compose.yaml and start it with docker compose up -d, then point your reverse proxy at the frontend container (127.0.0.1:8181). The nginx inside the frontend container already proxies /api/ and /public/display/ to the backend, so no separate backend port forwarding is needed.

Local Network Bridge

Home Assistant, an OpenEPaperLink access point, and a CUPS printer are usually only reachable from the same local network as the backend. If the backend is hosted somewhere without direct access to that network (e.g. the cloud), run the small bridge client (bridge/, image Dockerfile.bridge) on the local network instead — it holds a permanent WebSocket connection open to the backend and proxies those three integrations' HTTP traffic through it. Self-hosted setups where the backend already lives on the same network don't need it; without a bridge connected, the backend talks to those services directly, exactly as before.

Setup:

  1. In the web UI, go to Devices and generate a registration code.

  2. Exchange it for a permanent device token:

    docker run --rm jonasled.dev/jonasled/filamentmanagement/bridge:latest \
      -register -server https://your-instance.example.com -code ABCD-1234 -name "Home bridge"
    
  3. Run the bridge with that token (keep it running, e.g. via docker run -d or a systemd unit):

    docker run -d --restart unless-stopped \
      -e FM_SERVER_URL=https://your-instance.example.com \
      -e FM_DEVICE_TOKEN=fmdt_... \
      jonasled.dev/jonasled/filamentmanagement/bridge:latest
    

The Devices page shows whether a bridge is currently connected. Revoking its device token disconnects it immediately.

Multiple backend replicas (Kubernetes/HA)

A bridge holds one WebSocket connection to one specific backend pod. If the backend runs as more than one replica (see autoscaling in helm/values.yaml), only that one pod could otherwise route requests through it. Set REDIS_ADDR (backend env var; redis.addr in the Helm chart, plus redis.db) to fix that: every pod pushes bridge requests onto a shared Redis queue, and whichever pod currently holds the live connection claims and answers them, so it doesn't matter which pod handled the original request. This also means a request made while the bridge is reconnecting (a brief network blip, or it moving to a different pod) still queues up and succeeds once it's back, rather than failing. A single-replica deployment doesn't need Redis — this is opt-in and only relevant once you're running more than one backend pod.

Redis's password (if it needs one) can be set either way in the Helm chart:

  • redis.password: set inline, rendered into a Secret the chart creates and manages.
  • redis.existingSecret (+ redis.existingSecretPasswordKey, default password): point at a Secret you already manage yourself. Takes precedence over redis.password when both are set.