Skip to content

installation.md

Latest commit

 

History

History
83 lines (55 loc) · 1.83 KB

installation.md

File metadata and controls

83 lines (55 loc) · 1.83 KB

OpenStudbook Installation Guide

This guide covers a quick manual setup. The README is the canonical reference — see it for full configuration options, production deployment, and security notes.

Prerequisites

  • Node.js 18 LTS or higher (20 LTS recommended)
  • MariaDB 10.6+ or MySQL 8.0+ — must be running before you start
  • npm 9+ (bundled with Node)

Setup

1. Clone and install dependencies

git clone https://github.com/teruselearning/openstud.git
cd openstud
npm install
cd backend && npm install && cd ..

2. Configure the backend

cp backend/.env.example backend/.env

Open backend/.env and set at minimum:

JWT_SECRET=<long random string>
DATABASE_HOST=localhost
DATABASE_USER=root
DATABASE_PASSWORD=<your db password>
DATABASE_NAME=openstudbook

Generate a secure JWT secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. Create the database

mysql -u root -p -e "CREATE DATABASE openstudbook CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

4. Start the app

# Terminal 1 — backend
cd backend && npm run dev

# Terminal 2 — frontend
npm run dev

Open http://localhost:3000 — the installer wizard will guide you through the rest.

First Run

The web installer will:

  1. Verify your database connection
  2. Run all migrations and seed default data
  3. Create your first organisation and admin account

After setup, configure SMTP, languages, and feature flags under Super Admin (gear icon in the sidebar).

Production

See Production Deployment in the README for build steps, Nginx config, process management, and the security checklist.

Never expose the app publicly without completing the security checklist first.