Repository navigation
GradeShelf v1.0.0 — Initial release
GradeShelf 1.0.0
GradeShelf is a self-hosted, multi-user grade tracker and exam planner. Keep subjects, grades, upcoming exams, notes and attachments in one place, with separate private accounts for everyone using your instance.
This initial release brings the complete GradeShelf application to a single Docker container. It runs locally with SQLite and requires no cloud account, email service or external backend.
Grades and exams
- Create separate grade lists for school years, courses or qualifications, with their own subjects and grading scale.
- Define reusable grade types and weights. Each entry keeps its recorded weight, so changing a type does not rewrite past results.
- Plan an exam before it happens and add its grade later. The dashboard separates upcoming exams, results awaiting entry and recent grades.
- View weighted averages per subject, per list and across selected lists. Different grading scales remain separate.
- Follow recent performance with interactive charts based on a rolling window of up to ten grades.
- Use nine grading scales, including German school grades, upper-secondary points, US letter grades and percentages.
- Archive completed lists, choose a default list and configure which lists appear on your dashboard.
Personal workspace
- English and German, with a saved language preference for each user.
- Light, dark and system themes, plus layouts for phones, tablets and desktops.
- Guided setup for lists, subjects and grade types, available again in Settings.
- Notes and private PDF, JPEG, PNG, WEBP and HEIC/HEIF attachments.
- Complete ZIP exports with attachments, and printable PDF reports.
- Copy links to individual entries and open them directly after signing in.
Accounts and administration
Administrators create and manage users; there is no public registration. They can activate or deactivate accounts, reset passwords and reset two-factor authentication. Admin access does not grant access to another user's grades or files.
Users can enable TOTP two-factor authentication with a standard authenticator app and save recovery codes. Operators can configure an instance name, legal notice and administrator contact information.
Upload limits are configurable through environment variables: maximum file size, attachments per entry and total attachment storage per user. Users see storage usage and a warning at 80%. Reducing a limit never deletes existing files or blocks their download.
Install with Docker
Requires Docker with Compose v2, curl and OpenSSL. No Git clone or Node.js installation is needed on the host.
mkdir -p gradeshelf
cd gradeshelf
curl -fSL --proto '=https' --proto-redir '=https' \
https://raw.githubusercontent.com/14flavius/GradeShelf/main/scripts/install.sh \
-o install.sh &&
sh install.shThe installer creates the configuration, generates an authentication secret, prepares the data directory and starts the app. Set the browser URL to the exact address you will use, including https:// when serving it through your own reverse proxy.
Initial login: gradeshelf / gradeshelf0000. Change the password when prompted before exposing the instance publicly, then use the setup tutorial to create your first list.
Images and persistent data
- Image:
ghcr.io/14flavius/gradeshelf:1.0.0 - Stable channel:
ghcr.io/14flavius/gradeshelf:latest - Architectures:
linux/amd64andlinux/arm64 - Application: HTTP on port
3000 - Storage: host directory
./data, mounted at/data
The release workflow builds and publishes these image tags. Check GitHub Actions for build completion before installing this release.
The database and uploads remain on the host through container restarts, replacements and docker compose down. Updates apply versioned database migrations; a backup script is included. Keep the data directory and authentication secret, and maintain backups outside the server.
Installation, configuration and backups · Website
By Flavius Hager. Most of the original GradeShelf foundation was vibe-coded with AI assistance.