GradeShelf v1.3.2 - Footer fix and dependency updates

GradeShelf 1.3.2 is a small maintenance release.

Changes

• Fixed the GitHub link in the footer.
• Updated React (19.3.1), Tailwind CSS (4.3.4), jose and dotenv.

Updating

Back up and update from your installation directory:

sh scripts/backup.sh && docker compose pull && docker compose up -d --wait

Keep .env and data/. For pinned installations, use ghcr.io/14flavius/gradeshelf:1.3.2.

Full Changelog: v1.3.1...v1.3.2

GradeShelf v1.3.1 - Maintenance and dependency updates

GradeShelf 1.3.1 is a maintenance release with updated dependencies. There are no changes to features or data.

Changes

• Updated Better Auth (1.7.21) and Next.js (16.4.6), including refreshed transitive dependencies.
• The installer now downloads its configuration and scripts from the latest release, so new installations always match the published image.
• Docker images now carry a signed provenance attestation that links each image to its source commit.
• GradeShelf is now licensed under the MIT License.

Updating

Back up and update from your installation directory:

sh scripts/backup.sh && docker compose pull && docker compose up -d --wait

Keep .env and data/. For pinned installations, use ghcr.io/14flavius/gradeshelf:1.3.1.

Full Changelog: v1.3.0...v1.3.1

GradeShelf v1.3.0 - Flexible grading and course half-years

GradeShelf 1.3.0 adds flexible grading and course half-years while keeping simple grade lists easy to use.

Grades and course half-years

• Use simple grades, school-year halves or four course half-years, with separate grading scales in the same account.
• Set up subjects, course types, enrollment and shared weighting together, with optional exceptions per subject.
• Use percentage weighting, grouped assessments, decimal and tendency grades, and a target-grade calculator.
• Track received final grades separately from calculated averages. Exports and calendar entries include the relevant periods and groups.

Updating

For regular installations, back up and update:

sh scripts/backup.sh && docker compose pull && docker compose up -d --wait

Keep .env and data/; migrations preserve existing data. For pinned installations, use ghcr.io/14flavius/gradeshelf:1.3.0.

Customized v1.2.0 installations must use the import procedure first. Accounts and attachments are retained; review any unassigned periods or types afterwards.

Thanks

Thanks to Denis (@Denis5C) for the suggestions and shared implementation that helped shape the school and upper-secondary features.

GradeShelf v1.2.0 - SSO login and account roles

GradeShelf 1.2.0 adds support for SSO login through OpenID Connect and role changes for existing accounts.

SSO login

• Configure an OpenID Connect (OIDC) provider under Admin → Advanced features → SSO login. Check the provider configuration and copy the callback URL directly from the dashboard.
• Connect an existing account under Settings → Security → SSO login, then use the SSO login button for future sign-ins.
• Keep using the same account, grades, files and preferences. Local username and password sign-in remains available, including when the provider is unavailable.
• Manage SSO settings and account connections in English or German.

Accounts are still created by administrators. SSO does not automatically create accounts, merge them by email or synchronize roles from the provider.

Account roles

• Change existing accounts between User and Administrator in account administration.
• Administrators cannot change their own role. The last active administrator is also protected from demotion, deactivation and deletion.
• Role changes end the affected account's sessions without changing grades, files or SSO connections.
• Successful changes appear as admin.role_changed in the application logs, including the acting administrator's ID, affected account ID and previous and new roles.

Administrator access does not grant access to another user's grades or files.

Security and sessions

Connecting or disconnecting SSO requires a recent local sign-in, including local 2FA when enabled. Client secrets are encrypted, and provider tokens are not retained in the account database.

Saving SSO settings revokes existing SSO sessions. Disconnecting SSO revokes that account's SSO sessions. Configure two-factor authentication for SSO at your provider; GradeShelf's own TOTP protection applies to local password sign-in.

Updating

Back up your installation and update from its directory:

sh scripts/backup.sh && docker compose pull && docker compose up -d --wait

Keep your existing .env and data/ directory. The container runs the database migration automatically during startup. It adds SSO settings and session metadata without deleting or replacing existing accounts, grades or uploads.

For a pinned installation, set GRADESHELF_IMAGE to ghcr.io/14flavius/gradeshelf:1.2.0 before updating.

The release workflow builds images for amd64 and arm64 and publishes them after its build and persistence checks succeed. Wait for the Publish Docker image workflow to finish before pulling the update.

GradeShelf v1.1.0 - Calendar subscriptions

GradeShelf 1.1.0 adds private calendar subscriptions for your exams and grades.

Calendar subscriptions

• Enable a read-only ICS subscription in Settings → Calendar subscription and use it in Apple Calendar, Outlook or another ICS-compatible calendar app.
• Choose exactly which grade lists to include. Past and graded entries remain available; new lists are never added automatically.
• Customize event titles and descriptions with variables for the entry, subject, list, grade type, date, status, grade, weight, note and link. Preview the result using an existing entry.
• Copy a private subscription URL, replace it when needed or disable the subscription. Only a hash of the URL token is stored; the full URL is shown once after activation or replacement.
• Use the settings and preview in English or German, including on mobile devices.

Stable updates and privacy

Each entry keeps its calendar ID when its title, date or grade changes. Feeds are generated from a consistent database snapshot and replace the cache only when complete. Failed generation never returns a partially built or accidentally empty successful calendar.

Feeds use a bounded 60-second server cache, conditional requests and rate limiting. Access is checked before cached responses are served, so disabling a subscription or replacing its URL revokes the old URL immediately. The calendar app controls its own refresh interval and may update less often.

Notes and grade values are excluded from the default templates; attachments are never included. Calendar settings are included in personal data exports without subscription credentials. Treat the subscription URL like a password, use HTTPS and exclude /calendar/ URLs from reverse-proxy logs. Replacing a URL does not remove copies already downloaded by a calendar app; update the existing subscription rather than adding a duplicate calendar.

Also changed

Removed the login tagline in both English and German.

Updating

From your installation directory:

sh scripts/backup.sh && docker compose pull && docker compose up -d --wait

The container applies the new Prisma migration on startup. Keep your existing .env and data/ directory. The migration adds calendar tables without replacing existing user data. If you pin your image version, change GRADESHELF_IMAGE to ghcr.io/14flavius/gradeshelf:1.1.0 first.

The release workflow publishes ghcr.io/14flavius/gradeshelf:1.1.0 and :latest for amd64 and arm64 after its build and persistence checks pass. Wait for the Publish Docker image workflow to finish before updating.

Validation

Production build, TypeScript, ESLint and Prisma validation passed. Isolated tests covered migration data preservation, ownership checks, URL revocation, cache expiry, stable IDs, concurrent reads and failure handling. Production HTTP routes and mobile browser interactions were checked. A live subscription in Apple Calendar itself has not yet been verified.

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.sh

The 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/amd64 and linux/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.