Elijah
5db7fc8afd
All checks were successful
Verify and publish container / build-and-push (push) Successful in 1m26s
115 lines
4.4 KiB
Markdown
115 lines
4.4 KiB
Markdown
Study Desk is a self-hosted, single-user study application.
|
|
|
|
## Local development
|
|
|
|
```powershell
|
|
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.
|
|
|
|
```powershell
|
|
$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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
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:
|
|
|
|
```powershell
|
|
$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:
|
|
|
|
```bash
|
|
npm run dev
|
|
# or
|
|
yarn dev
|
|
# or
|
|
pnpm dev
|
|
# or
|
|
bun dev
|
|
```
|
|
|
|
Open [http://localhost:3000](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`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
|
|
|
|
## Learn More
|
|
|
|
To learn more about Next.js, take a look at the following resources:
|
|
|
|
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
|
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
|
|
|
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
|
|
|
## Deploy on Vercel
|
|
|
|
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
|
|
|
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
|