Gallus_Pub/backend/SETUP_QUICK_START.md

Quick Start Guide - SQLite Version

✅ Migration Complete: PostgreSQL → SQLite

The backend now uses SQLite instead of PostgreSQL for simplified deployment and lower costs.

🚀 Quick Start (3 Steps)

1. Configure Environment

Edit .env file (already created):

# Required: Update these values
GITEA_CLIENT_ID=<your-gitea-oauth-client-id>
GITEA_CLIENT_SECRET=<your-gitea-oauth-client-secret>
GIT_REPO_URL=https://git.bookageek.ch/<yourusername>/Gallus_Pub.git
GIT_TOKEN=<your-gitea-personal-access-token>
GITEA_ALLOWED_USERS=sabrina,raphael

# Already set (JWT secrets generated)
JWT_SECRET=dOrvUqifjBLvk68kkDOvWPQper/gjsNMlAbWlVBQIrc=
SESSION_SECRET=SD0ZrvLkv9GrtI8+3GDkxZXA1UnCN4CE3c4+2vA/fIM=

# Database (SQLite - no changes needed)
DATABASE_PATH=./data/gallus_cms.db

2. Initialize Database

# Generate migration files from schema
pnpm run db:generate

# Run migrations to create tables
pnpm run db:migrate

3. Start Development Server

pnpm run dev

Server will start at http://localhost:3000

📝 What Changed?

Before (PostgreSQL)

• Required PostgreSQL installation
• Separate database service
• Connection string configuration
• ~$15/month hosting cost on Fly.io

After (SQLite)

• Single file database (./data/gallus_cms.db)
• No separate database service needed
• Works out of the box
• $0 database cost (included in app volume)

🗂️ Database Location

• Local: ./data/gallus_cms.db
• Production (Fly.io): /app/data/gallus_cms.db (on persistent volume)
• Git Workspace: Same data/ directory

🧪 Test Authentication Flow

1. Make sure you have Gitea OAuth credentials configured
2. Start dev server: pnpm run dev
3. Visit: http://localhost:3000/api/auth/gitea
4. Login with your Gitea credentials
5. Should redirect back with JWT token

📚 Available Endpoints

Health Check

curl http://localhost:3000/health

OAuth Flow

GET /api/auth/gitea - Initiate OAuth
GET /api/auth/callback - OAuth callback
GET /api/auth/me - Get current user (requires JWT)

Content Management (all require JWT)

GET/POST/PUT/DELETE /api/events
GET/POST/PUT/DELETE /api/gallery
GET/PUT /api/content/:section
GET/PUT /api/settings/:key
POST /api/publish

🔐 Getting Gitea OAuth Credentials

1. Go to https://git.bookageek.ch/user/settings/applications
2. Click "Manage OAuth2 Applications"
3. Create new OAuth2 application:
   • Name: Gallus Pub CMS
   • Redirect URI: http://localhost:3000/api/auth/callback
   • Confidential: Yes
4. Copy Client ID and Client Secret to .env

🎫 Getting Gitea Personal Access Token

1. Go to https://git.bookageek.ch/user/settings/applications
2. Generate New Token
3. Name: Gallus CMS Backend
4. Scopes: Select repo (full repository access)
5. Copy token to .env as GIT_TOKEN

📦 Project Structure

backend/
├── data/                   # SQLite database & git workspace (gitignored)
│   ├── gallus_cms.db      # Database file
│   └── workspace/         # Git repository clone
├── src/
│   ├── config/
│   │   ├── database.ts    # SQLite connection (updated)
│   │   └── env.ts         # DATABASE_PATH instead of URL
│   ├── db/
│   │   └── schema.ts      # SQLite schema (updated)
│   ├── routes/            # API routes
│   ├── services/          # Core services
│   └── index.ts           # Main server
├── .env                   # Your configuration
├── package.json           # Updated with better-sqlite3
└── drizzle.config.ts      # SQLite dialect

⚙️ Scripts

pnpm install       # Install dependencies (done)
pnpm run dev       # Start dev server with watch
pnpm run build     # Build TypeScript
pnpm run start     # Start production server
pnpm run db:generate  # Generate migrations
pnpm run db:migrate   # Run migrations
pnpm run db:studio    # Open Drizzle Studio

🚀 Deploy to Fly.io

See DEPLOYMENT.md for full deployment guide.

Quick version:

# Create volume for database & git workspace
flyctl volumes create gallus_data --size 2 --region ams

# Set secrets
flyctl secrets set GITEA_CLIENT_ID=... GITEA_CLIENT_SECRET=... # etc

# Deploy
flyctl deploy

Cost: ~$5-10/month (no separate database!)

🐛 Troubleshooting

"tsx: command not found"

pnpm install

"DATABASE_PATH not set"

Check .env file exists and has DATABASE_PATH=./data/gallus_cms.db

"Database file not found"

mkdir -p data
pnpm run db:migrate

"better-sqlite3" build errors

Make sure you have build tools:

• Linux: apt-get install python3 make g++
• macOS: Install Xcode Command Line Tools
• Windows: Install windows-build-tools

Then rebuild:

pnpm rebuild better-sqlite3

✨ Benefits of SQLite

1. Simpler - No database server to manage
2. Faster - No network overhead
3. Portable - Single file, easy backups
4. Cost-effective - No hosting fees
5. Perfect fit - Low concurrency, simple queries

📖 Documentation

• SQLITE_MIGRATION.md - Detailed migration notes
• DEPLOYMENT.md - Fly.io deployment guide
• README.md - General setup instructions
• CMS_GITEA_AUTH.md - OAuth authentication details (parent dir)
• CMS_CONCEPT.md - Full system architecture (parent dir)

✅ Ready to Go!

Your backend is now configured for SQLite. Just:

1. Add your Gitea credentials to .env
2. Run pnpm run db:generate && pnpm run db:migrate
3. Start with pnpm run dev

Happy coding! 🎉