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):
```bash
# 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

```bash
# Generate migration files from schema
pnpm run db:generate

# Run migrations to create tables
pnpm run db:migrate
```

### 3. Start Development Server

```bash
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
```bash
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

```bash
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:**
```bash
# 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"
```bash
pnpm install
```

### "DATABASE_PATH not set"
Check `.env` file exists and has `DATABASE_PATH=./data/gallus_cms.db`

### "Database file not found"
```bash
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:
```bash
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! 🎉