Goldmine V2

Goldmine V2 is a web app for managing university lecture materials (exercise sheets, solutions, and related metadata). It is primarily designed as an internal tool for course staff to keep materials organized and consistent across semesters.

Project status

Goldmine V2 has not been battle-tested in a production setting and is currently maintained as a private/internal project. If you want to deploy it or get involved in development, please reach out and/or open a PR.

Features

• Lecture catalog with semesters and series (exercise sheets)
• PDF/TeX/solution uploads plus bulk import helpers
• HTML rendering of TeX via background render jobs
• Full-text search across lectures, series, and exercises
• Comments on exercises
• Role-based access (staff / professor / assistant) and course memberships
• Soft delete + trash restore with audit metadata
• Issue dashboard for missing/failed assets

Use cases

• Internal knowledge base for teaching staff
• Coordinated management of lecture materials across semesters

Intended audience

• Course staff and administrators
• Teaching assistants
• Professors
• Ops/DevOps teams hosting the service

Potential student-facing extension (future work)

Goldmine V2 could be extended to be student-facing, but that requires additional features and stricter access controls:

• Read-only student role: students should never edit content and should only access semesters they've been explicitly granted.
• Release scheduling: enforce timed release of series and solutions when uploading exercise sheets.
• Interactive assignments/quizzes: a next-level extension for interactive teaching tools and/or homework workflows.

Tech stack

• Frontend: Next.js (App Router), React, Tailwind CSS, SWR
• Backend: Django + django-ninja (+ django-rq workers)
• Datastores: Postgres (primary), Redis (jobs/queue)
• Rendering: LaTeXML/TeXLive + MathJax (client-side)
• Containerized with Docker; Caddy reverse proxy for production

Quick start (dev)

From the repo root:

# Recommended: use the helper script (starts db+redis+migrate+backend+worker+frontend)
./scripts/gm.sh dev up

# Or run Docker Compose directly
docker compose up -d --build

• Frontend: http://localhost:3000
• Backend (direct): http://localhost:8000 (API: /api, Django admin: /admin)

The frontend proxies /api, /admin, /static, and /media to the backend (single-origin cookies/CSRF), so for most workflows you can just use http://localhost:3000.

Helper script (recommended) for common dev flows:

./scripts/gm.sh dev down    # stop services (keeps volumes)
./scripts/gm.sh dev reset   # stop + delete volumes
./scripts/gm.sh dev empty   # fresh empty DB
./scripts/gm.sh dev demo    # fresh DB + demo seed

Create an admin user:

# Interactive (prompts for credentials; requires the stack running)
./scripts/gm.sh dev ensure-admin

# Or non-interactive
DJANGO_SUPERUSER_USERNAME=admin DJANGO_SUPERUSER_PASSWORD=change_me ./scripts/gm.sh dev ensure-admin

To auto-create the admin user after ./scripts/gm.sh dev up, set these env vars before running it.

Alternatively, use Django’s interactive command:

docker compose exec backend python manage.py createsuperuser

Seed demo data (optional):

./scripts/gm.sh dev seed-demo

The example TeX lives in backend/examples/demo_upload and is imported using the same upload detection flow as real data; placeholder PDFs are generated at seed time. A ready-to-upload demo archive is generated by python scripts/build_demo_zip.py and written to backend/examples/demo_upload.zip. Upload commits also create Exercise rows by scanning TeX headings/markers (best-effort) and automatically queue an HTML render job (see the “HTML Render” page). Set SEED_DEV_RENDER=0 to skip LaTeXML rendering.

Production

See DEPLOYMENT.md for Docker + Caddy deployment and backup guidance.

Render demo deployment (optional)

This repo also ships a lightweight Render Blueprint in render.yaml for “one-click” demo deployments (not intended as a full production setup).

• Deploys Postgres + Redis + backend + frontend
• Frontend proxies /api, /admin, /static, and /media to the backend so auth cookies/CSRF work on a single origin
• If you don’t have shell access (e.g. Render free tier), set DJANGO_SUPERUSER_USERNAME + DJANGO_SUPERUSER_PASSWORD (optional DJANGO_SUPERUSER_EMAIL) on the backend service and redeploy/restart

Configuration

• Example backend env file: backend/.env.example (for local, non-Docker usage)
• Production uses a root .env consumed by docker-compose.prod.yml
• Do not commit real secrets; use environment variables or secret managers

Repo layout

• backend/ Django app + API
• frontend/ Next.js app
• docker-compose.yml local dev stack
• docker-compose.prod.yml production stack
• Caddyfile reverse proxy config
• render.yaml Render.com demo blueprint
• scripts/ deploy and backup helpers

Background

This is a full bottom-up reimagined implementation of a similar system we had at ITP at ETH Zurich during the time I was a PhD student there.

Author

Dr. Tobias Wolf - tobiaswolf.net

License

AGPL-3.0-only. See LICENSE.