docs/SERVER_MODE.md

# Server Mode - Self-Hosting Guide

Self-host OSW Studio with persistence, authentication, and static site publishing.

---

## Overview

OSW Studio supports two deployment modes:

- **Browser Mode** (default): Pure client-side application using IndexedDB
- **Server Mode**: Full-stack deployment with publishing

Server Mode adds:
- Local database for persistent storage (no external database needed)
- Admin authentication with JWT sessions
- Sites publishing system with static site serving
- Project sync between browser and server
- Built-in analytics and compliance features

---

## Browser Mode vs Server Mode

### Browser Mode (Default)

**Characteristics:**
- No backend required
- Deploy to any static host (Vercel, Netlify, GitHub Pages, HuggingFace)
- Zero configuration
- Complete privacy (data never leaves browser)
- No multi-user support
- No server-side persistence
- No static site publishing

**Use Cases:**
- Personal development environment
- Quick prototyping
- Privacy-focused workflows
- Static deployment (HuggingFace Spaces)

### Server Mode

**Characteristics:**
- Local persistence (no external database)
- Admin authentication
- Multiple sites per project
- Static site publishing at `/sites/{siteId}/`
- Built-in analytics
- Project sync (browser <-> server)
- Requires persistent file system
- Requires server hosting

**Use Cases:**
- Production deployments
- Multi-user environments
- Publishing static sites
- Persistent project storage

---

## Quick Start

### 1. Configure Environment

Create `.env` file in project root:

```bash
# Enable Server Mode
NEXT_PUBLIC_SERVER_MODE=true

# Session security (generate with: openssl rand -base64 32)
SESSION_SECRET=your_random_secret_here

# Admin password
ADMIN_PASSWORD=your_secure_password_here

# Optional: Analytics secret
ANALYTICS_SECRET=your_analytics_secret_here

# Optional: Secrets encryption (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))")
SECRETS_ENCRYPTION_KEY=your_encryption_key_here

# Optional: App URL (for SEO/sitemaps)
NEXT_PUBLIC_APP_URL=https://your-domain.com
```

### 2. Start Server

```bash
npm install
npm run dev
```

SQLite databases are created automatically:
- `data/osws.sqlite` - Core database (projects, templates, skills)
- `sites/{siteId}/site.sqlite` - Per-site databases (files, settings, analytics)

### 3. Access Application

- **Studio**: http://localhost:3000/
- **Admin panel**: http://localhost:3000/admin/login
- **Published sites**: http://localhost:3000/sites/{siteId}/

**Login with** ADMIN_PASSWORD from .env

---

## Server Context Integration

In Server Mode, the AI gains awareness of your site's server features through a special `/.server/` folder that appears in the file explorer.

### How It Works

When you select a site from the **Site Selector** dropdown (in the workspace header), OSW Studio:
1. Loads that site's server features (edge functions, database schema, server functions, secrets)
2. Mounts them as transient files in `/.server/`
3. Informs the AI about these capabilities in its system prompt

### The `/.server/` Folder

This hidden folder contains:
- **db/schema.sql** - Database schema (read-only, use `sqlite3` for DDL)
- **edge-functions/*.json** - Edge functions (editable via `json_patch`)
- **server-functions/*.json** - Server functions (editable via `json_patch`)
- **secrets/*.json** - Secret placeholders (editable - AI creates, user sets values in admin UI)

These files are:
- **Transient** - They are not saved with the project
- **Auto-updated** - They reflect the current site's state
- **Partially editable** - Schema is read-only, but functions and secrets can be modified

### Using Server Features with AI

Once a site is selected, you can ask the AI to:

```
What edge functions are available for this site?
```

```
Help me create an edge function that uses the products table
```

```
Show me the database schema
```

The AI will use the `/.server/` files to understand your site's capabilities and provide relevant assistance.

### Viewing the `/.server/` Folder

The folder is hidden by default. To view it:
1. Right-click in the File Explorer
2. Select **Show Hidden Files**
3. The `/.server/` folder appears with an orange server icon

---

## Project Sync

Server Mode uses a hybrid storage approach: projects are edited locally in the browser (for speed) and synced to the server (for persistence). This gives you the best of both worlds - fast local editing with server-side backup.

### How Sync Works

**Automatic Push (on save):**
When you save a project in Server Mode, it automatically syncs to the server. You'll see a brief "Project synced" notification.

**Automatic Pull (on load):**
When you open the Project Manager, OSW Studio checks for any updates from the server and pulls them automatically. Projects that exist on the server but not locally are downloaded.

**Manual Sync:**
For bulk operations or troubleshooting, use the Sync button in the sidebar. This opens a dialog where you can:
- **Push to Server** - Upload all local projects to the database
- **Pull from Server** - Download all server projects to your browser

### When to Use Manual Sync

- **Setting up a new browser** - Pull to populate your IndexedDB from the server
- **After server restore** - Pull to get the restored data locally
- **Troubleshooting** - Force push/pull if auto-sync isn't working

---

## Deployment Options

> **Important**: Server Mode requires **persistent file system** storage because published sites are written to `/public/sites/` and databases are stored locally. Serverless platforms like Vercel, Netlify, and Cloudflare Workers **will not work** for Server Mode.

### Option 1: Railway (Recommended)

**Why**: Simple setup, persistent storage, usage-based pricing

**Pricing**: $5/month minimum (includes $5 in usage credits). Free trial: 30 days with $5 credits.

**Steps:**

1. **Create Railway Account:**
   - Go to https://railway.app
   - Sign up with GitHub

2. **New Project:**
   - Click "New Project"
   - Select "Deploy from GitHub repo"
   - Choose your OSW Studio fork

3. **Configure Variables:**
   - Go to project variables
   - Add:
     ```
     NEXT_PUBLIC_SERVER_MODE=true
     SESSION_SECRET=<generate>
     ADMIN_PASSWORD=<your password>
     NEXT_PUBLIC_APP_URL=${{ RAILWAY_PUBLIC_DOMAIN }}
     ```

4. **Deploy:**
   - Railway auto-deploys on push
   - Access at: `https://your-project.up.railway.app`

---

### Option 2: VPS (Full Control)

**Why**: Complete control, custom domains, lowest cost at scale

**Requirements:**
- Ubuntu 22.04+ server
- SSH access
- Domain (optional)

**Steps:**

1. **Install Dependencies:**
   ```bash
   # Update system
   sudo apt update && sudo apt upgrade -y

   # Install Node.js 18+
   curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
   sudo apt install -y nodejs

   # Install git
   sudo apt install -y git
   ```

2. **Clone and Configure:**
   ```bash
   # Clone repository
   git clone https://github.com/o-stahl/osw-studio.git
   cd osw-studio

   # Install dependencies
   npm install

   # Create .env
   nano .env
   ```

   Paste:
   ```
   NEXT_PUBLIC_SERVER_MODE=true
   SESSION_SECRET=<generate with: openssl rand -base64 32>
   ADMIN_PASSWORD=<your password>
   NEXT_PUBLIC_APP_URL=http://your-domain.com
   # SECURE_COOKIES=false  # Uncomment until SSL is configured
   ```

   > **Note**: If you're setting up without SSL initially, uncomment `SECURE_COOKIES=false` to allow login over HTTP. Re-comment or remove this line after configuring SSL with certbot (Step 5).

3. **Build and Start:**
   ```bash
   # Production build
   npm run build

   # Start with PM2 (process manager)
   sudo npm install -g pm2
   pm2 start npm --name "osw-studio" -- start
   pm2 save
   pm2 startup
   ```

4. **Setup Nginx (Reverse Proxy):**
   ```bash
   sudo apt install -y nginx
   sudo nano /etc/nginx/sites-available/osw-studio
   ```

   Paste:
   ```nginx
   server {
       listen 80;
       server_name your-domain.com;

       location / {
           proxy_pass http://localhost:3000;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
   }
   ```

   Enable:
   ```bash
   sudo ln -s /etc/nginx/sites-available/osw-studio /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl restart nginx
   ```

5. **Setup SSL (Let's Encrypt):**
   ```bash
   sudo apt install -y certbot python3-certbot-nginx
   sudo certbot --nginx -d your-domain.com
   ```

**Access:**
- http://your-domain.com (redirects to HTTPS)
- https://your-domain.com/admin/login

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NEXT_PUBLIC_SERVER_MODE` | Yes | Set to `true` to enable Server Mode |
| `SESSION_SECRET` | Yes | Random string for JWT signing |
| `ADMIN_PASSWORD` | Yes | Password for admin login |
| `ANALYTICS_SECRET` | No | Secret for analytics API |
| `SECRETS_ENCRYPTION_KEY` | No | 256-bit key for encrypting secrets |
| `SECURE_COOKIES` | No | Set to `false` to allow insecure cookies (pre-SSL only) |
| `NEXT_PUBLIC_APP_URL` | No | Base URL for SEO/sitemaps |

---

## Troubleshooting

### Database Issues

**Symptoms**: "Failed to initialize database"

**Solutions**:
1. Check write permissions on `data/` directory
2. Ensure disk space is available
3. Check file system supports SQLite (most do)
4. Try deleting `data/osws.sqlite` and restarting (loses data)

### Migration Failures

**Symptoms**: Tables not created, "relation does not exist"

**Solutions**:
1. Migrations run automatically on first request
2. Check terminal logs for errors
3. Restart the server to trigger migrations

### Authentication Issues

**Symptoms**: Can't login to /admin

**Solutions**:
1. Verify `ADMIN_PASSWORD` is set in .env
2. Try resetting password:
   ```bash
   # Update .env
   ADMIN_PASSWORD=new_password_here

   # Restart server
   pm2 restart osw-studio  # or npm run dev
   ```
3. Clear browser cookies
4. Try incognito mode
5. Check `SESSION_SECRET` is set

### Performance Issues

**Symptoms**: Slow site loads, high memory

**Solutions**:
1. Optimize published sites:
   - Compress images
   - Minify CSS/JS
   - Use CDN for libraries
2. Monitor server resources:
   ```bash
   htop  # or top
   df -h  # disk space
   free -m  # memory
   ```
3. Scale server resources (RAM/CPU)
4. Add caching (Nginx cache)

---

## Next Steps

- **[Site Publishing](?doc=site-publishing)** - Publish sites with analytics, SEO, compliance
- **[Server Features](?doc=server-features)** - Database, edge functions, secrets
- **[FAQ](?doc=faq)** - Common Server Mode questions
- **[Troubleshooting](?doc=troubleshooting)** - Fix common issues