Getting Started

This page helps you run CSMS locally and perform the first database initialization.

Requirements

Dependency	Version	Notes
Node.js	≥ 18 (22+ recommended)	Run & build CSMS
Package manager	npm / pnpm	Install dependencies
Database	SQLite (built-in)	No extra install; driven by Drizzle

This documentation uses Node.js 22 as an example. Windows users should use PowerShell 5.1+.

Install

# 1. Get the source
git clone https://github.com/QianKunBoss/ClassScoreManageSystem.git
cd ClassScoreManageSystem

# 2. Install dependencies
npm install
# or pnpm (this repo pins pnpm@9.9.0)
# pnpm install

Environment Variables

Copy the example env file and edit as needed:

cp .env.example .env

Key variables:

Variable	Required	Notes
`NUXT_SESSION_PASSWORD`	✅	Session encryption key, effective at runtime in any deployment. Generate with `openssl rand -hex 32`
`SESSION_SECRET`	⚪	Build-time fallback; runtime change has no effect
`HOST`	⚪	Listen address, default `::`
`PORT`	⚪	Listen port, default `3000`
`NODE_ENV`	⚪	Runtime environment

Warning

NUXT_SESSION_PASSWORD must be set even when using a prebuilt artifact (.output) on Windows, otherwise the server won't start.

Initialize the Database

npm run db:generate   # generate migrations from schema
npm run db:migrate    # apply migrations (creates main + per-school tables)
# npm run db:push     # (optional) sync schema directly, no migration files
# npm run db:studio   # (optional) open Drizzle Studio

Development Mode

npm run dev

Serves at http://localhost:3000 by default. After first start, open the homepage and follow to complete school onboarding and create the first admin.

Production Build

npm run build
# output is in .output/
npm run preview
# or run directly
node .output/server/index.mjs

For the various production deployment options (Docker / PM2 / Windows / Baota), see .

Database Commands

Command	Purpose
`npm run db:generate`	Generate migration SQL from schema
`npm run db:migrate`	Apply migrations
`npm run db:push`	Sync schema directly (skip migration files)
`npm run db:studio`	Launch Drizzle Studio to browse data

Data Persistence & Backup

All CSMS data lives under data/:

Main DB: data/csms.db (schools, admins, announcements, API tokens, etc.)
Per-school DBs: data/schools/{schoolId}.db (grades, classes, students, scores, etc.)

data/ is already in .gitignore. To back up, just copy these files — see .