Why Self-Host?
Sunschool is open source and designed for easy self-hosting, giving you complete control over your educational platform:Data Ownership
Your data stays on your infrastructure. Nothing gets sold or used to train external models.
Privacy Control
Keep sensitive student information in your own environment with full audit capability.
Customization
Modify prompts, features, and workflows to match your educational philosophy.
Transparency
Read the code, audit the AI prompts, and verify exactly how the system works.
Architecture Overview
Sunschool uses a modern, production-ready stack:Technology Stack
Deployment Options
Cloud Platforms
Railway (Recommended)
Railway (Recommended)
Railway provides zero-config deployment with automatic builds:
- Auto-deploy on push to
mainbranch - Built-in PostgreSQL database
- Health check monitoring at
/api/healthcheck - Uses NIXPACKS builder (Node 22)
- Production config in
railway.jsonandnixpacks.toml
Vercel / Netlify
Vercel / Netlify
Deploy the frontend static build:Point your serverless functions to the backend or deploy separately.
Docker
Docker
Build and run with Docker:Requires PostgreSQL database accessible from container.
VPS (DigitalOcean, Linode, etc.)
VPS (DigitalOcean, Linode, etc.)
Install Node.js 22, PostgreSQL, and run:Use PM2 or systemd for process management.
Local Development
For development and testing:http://localhost:5000 with hot reload.
System Requirements
- Node.js: v20+ (v22 recommended)
- PostgreSQL: 12+ (Neon serverless supported)
- npm: 8+
- Memory: 512MB minimum (2GB+ recommended)
- Storage: 1GB+ for application and database
Key Features
AI-Powered Learning
- Grade-specific prompts - K-2, 3-4, 5-6, 7-8, 9+ with reading level validation
- Multi-provider AI - OpenRouter primary with Bittensor fallback
- SVG illustrations - LLM-generated educational graphics via Gemini 3.1
- Adaptive quizzes - Concept mastery tracking with spaced repetition
Security & Authentication
- JWT-based auth - Secure token-based authentication
- Role-based access - Admin, Parent, and Learner roles
- Password hashing - scrypt with salt for secure storage
- First user admin - Automatic admin promotion for initial user
Data Management
- Auto migrations - Schema updates run on server startup
- External sync - Optional PostgreSQL backup connections
- Data export - Full data export capability for parents/admins
- Privacy-first - No external tracking or data sharing
Next Steps
System Requirements
Verify your environment meets the prerequisites
Environment Setup
Configure environment variables and API keys
Database Setup
Initialize PostgreSQL and run migrations
Security
Implement authentication and access controls
Support
For issues or questions: