- Go 50.2%
- TypeScript 31.7%
- C 11.9%
- C++ 4.7%
- HTML 1%
- Other 0.5%
|
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
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| .forgejo/workflows | ||
| .vscode | ||
| backend | ||
| bridge | ||
| container | ||
| documentation | ||
| filamentmanagement-display | ||
| frontend | ||
| graphify-out | ||
| helm | ||
| .gitignore | ||
| .gitmodules | ||
| CLAUDE.md | ||
| compose.yaml | ||
| Dockerfile.backend | ||
| Dockerfile.bridge | ||
| Dockerfile.frontend | ||
| README.md | ||
| renovate.json | ||
Filament Management
A web app for managing filament spools, vendors, and inventory with a Go backend and a React + MUI frontend.
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) ormysqlDB_NAME: SQLite file name or MySQL database nameDB_USER: MySQL userDB_PASSWORD: MySQL passwordDB_HOST: MySQL hostDB_PORT: MySQL port (default3306)EXECUTE_MIGRATIONS:true(default) to run migrations on startup. Set tofalsewhen running them separately with themigratecommand (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,
-1in 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/loginredirects to the provider/api/v1/oidc/callbackcreates the user on first login and issues a session cookie/api/v1/oidc/configexposes 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:
-
In the web UI, go to Devices and generate a registration code.
-
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" -
Run the bridge with that token (keep it running, e.g. via
docker run -dor 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, defaultpassword): point at a Secret you already manage yourself. Takes precedence overredis.passwordwhen both are set.