Study/README.md

Study Desk is a self-hosted, single-user study application.

Local development

npm.cmd ci
npx.cmd prisma generate
npm.cmd run dev

The automated test harness always creates a uniquely named database under .test-databases/, applies committed migrations, and removes the database after the run. It refuses dev.db, /app/data/study.db, existing databases, and paths that are not explicitly test-named.

Production container

Set a unique session secret of at least 32 characters. Production startup fails before migrations or the HTTP server when the secret is missing, short, or the published development fallback.

$env:SESSION_SECRET = '<at-least-32-random-characters>'
docker compose -f docker-compose.yml up --build

The host listens on http://localhost:3000; the container listens on port 3726. Development Compose is intentionally explicit and is never auto-merged:

docker compose -f docker-compose.dev.yml up --build

For first-time production setup, either provide an Argon2 encoded ADMIN_PASSWORD_HASH, or temporarily set ALLOW_INITIAL_SETUP=true for the one-time setup request. Remove the flag after setup. Production HTTP password reset initiation is unavailable; run this on the server instead:

npm.cmd run auth:reset

If TLS terminates at a trusted reverse proxy, forward requests only from that proxy and set SECURE_COOKIES=true. Leave it false for intentional plain HTTP; Secure cookies cannot be used over plain HTTP.

Database backup, migration adoption, and restore

Never run migration tests against the only copy of a study database. Create a lock-safe SQLite backup through the backup API and verify it before deployment:

$env:DATABASE_URL = 'file:./data/study.db'
npm.cmd run db:backup -- --output ./backups/study-before-upgrade.db
npm.cmd run db:preflight
npx.cmd prisma migrate deploy

The material-group preflight reports one of four states:

• APPLY: migration history is complete and the group schema is absent; run prisma migrate deploy normally.
• ADOPT: prior migrations are tracked and the database exactly matches the intended schema of one or more unrecorded committed migrations. This includes recovery from P3018 when an already schema-pushed table or column exists. After reviewing the verified backup, explicitly run npm run db:preflight -- --resolve --backup <backup-path>.
• CURRENT: migration and schema already agree.
• CONFLICT: partial or unknown state. Stop and recover manually; do not use db push, reset, edit applied migrations, or mark anything applied.

The production entrypoint runs this preflight before prisma migrate deploy. It refuses ADOPT and CONFLICT states without changing migration history; adoption always remains an explicit backup-gated operator action.

Restore drill: stop Study Desk, keep the damaged database as evidence, restore the verified backup to a new path, run SQLite integrity_check plus npm run db:preflight, start the same prior application image against the restored path, and compare class/deck/quiz counts plus representative content. Only swap the production path after those checks pass.

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.