Leon4gr45/builder

1# Server Mode - Self-Hosting Guide2 3Self-host OSW Studio with persistence, authentication, and static site publishing.4 5---6 7## Overview8 9OSW Studio supports two deployment modes:10 11- **Browser Mode** (default): Pure client-side application using IndexedDB12- **Server Mode**: Full-stack deployment with publishing13 14Server Mode adds:15- Local database for persistent storage (no external database needed)16- Admin authentication with JWT sessions17- Deployment publishing system with static site serving18- Project sync between browser and server19- Server-side generation (AI tasks continue if browser disconnects, reattach on reconnect)20- Built-in analytics and compliance features21 22---23 24## Browser Mode vs Server Mode25 26### Browser Mode (Default)27 28**Characteristics:**29- No backend required30- Deploy to any static host (Vercel, Netlify, GitHub Pages, HuggingFace)31- Zero configuration32- Complete privacy (data never leaves browser)33- No multi-user support34- No server-side persistence35- No static site publishing36 37**Use Cases:**38- Personal development environment39- Quick prototyping40- Privacy-focused workflows41- Static deployment (HuggingFace Spaces)42 43### Server Mode44 45**Characteristics:**46- Local persistence (no external database)47- Admin authentication48- Multiple deployments per project49- Static site publishing at `/deployments/{id}/`50- Built-in analytics51- Project sync (browser <-> server)52- Server-side generation (close browser, AI keeps working)53- Requires persistent file system54- Requires server hosting55 56**Use Cases:**57- Production deployments58- Multi-user environments (see **[Multitenancy](?doc=multitenancy)**)59- Publishing static sites60- Persistent project storage61 62---63 64## Quick Start65 66### 1. Configure Environment67 68Create `.env` file in project root:69 70```bash71# Enable Server Mode72NEXT_PUBLIC_SERVER_MODE=true73 74# Session security (generate with: openssl rand -base64 32)75SESSION_SECRET=your_random_secret_here76 77# Admin password (optional — only needed for headless/scripted bootstrap)78# For interactive setup, skip this and create admin via /admin/register on first visit79# ADMIN_PASSWORD=your_secure_password_here80 81# Optional: Analytics secret82ANALYTICS_SECRET=your_analytics_secret_here83 84# Optional: Secrets encryption (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))")85SECRETS_ENCRYPTION_KEY=your_encryption_key_here86 87# Optional: App URL (for SEO/sitemaps)88NEXT_PUBLIC_APP_URL=https://your-domain.com89```90 91### 2. Start Server92 93```bash94npm install95npm run dev96```97 98SQLite databases are created automatically:99- `data/osws.sqlite` - Core database (projects, deployments, templates, skills)100- `deployments/{id}/runtime.sqlite` - Per-deployment runtime (edge functions, secrets, user tables)101- `deployments/{id}/analytics.sqlite` - Per-deployment analytics (pageviews, sessions)102 103### 3. Access Application104 105- **Studio**: http://localhost:3000/106- **Admin panel**: http://localhost:3000/admin/login107- **Published sites**: http://localhost:3000/deployments/{id}/108 109**On first visit**, you'll be prompted to create an admin account. After login, you'll land on the **Dashboard** with server stats and traffic metrics.110 111---112 113## Server Context Integration114 115In Server Mode, the AI gains awareness of your deployment's backend features through a special `/.server/` folder that appears in the file explorer.116 117### How It Works118 119When you select a deployment from the **Deployment Selector** dropdown (in the workspace header), OSW Studio:1201. Loads that deployment's backend features (edge functions, database schema, server functions, secrets)1212. Mounts them as transient files in `/.server/`1223. Informs the AI about these capabilities in its system prompt123 124### The `/.server/` Folder125 126This hidden folder contains:127- **db/schema.sql** - Database schema (read-only, use `sqlite3` for DDL)128- **edge-functions/*.json** - Edge functions (editable via shell commands)129- **server-functions/*.json** - Server functions (editable via shell commands)130- **secrets/*.json** - Secret placeholders (editable - AI creates, user sets values in admin UI)131 132These files are:133- **Transient** - They are not saved with the project134- **Auto-updated** - They reflect the current deployment's state135- **Partially editable** - Schema is read-only, but functions and secrets can be modified136 137### Using Backend Features with AI138 139Once a deployment is selected, you can ask the AI to:140 141```142What edge functions are available for this deployment?143```144 145```146Help me create an edge function that uses the products table147```148 149```150Show me the database schema151```152 153The AI will use the `/.server/` files to understand your deployment's capabilities and provide relevant assistance.154 155### Viewing the `/.server/` Folder156 157The folder is hidden by default. To view it:1581. Right-click in the File Explorer1592. Select **Show Hidden Files**1603. The `/.server/` folder appears with an orange server icon161 162---163 164## Project Sync165 166Server 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.167 168### How Sync Works169 170**Automatic Push (on save):**171When you save a project in Server Mode, it automatically syncs to the server. You'll see a brief "Project synced" notification.172 173**Automatic Pull (on load):**174When 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.175 176**Manual Sync:**177For bulk operations or troubleshooting, use the Sync button in the sidebar. This opens a dialog where you can:178- **Push to Server** - Upload all local projects to the database179- **Pull from Server** - Download all server projects to your browser180 181### When to Use Manual Sync182 183- **Setting up a new browser** - Pull to populate your IndexedDB from the server184- **After server restore** - Pull to get the restored data locally185- **Troubleshooting** - Force push/pull if auto-sync isn't working186 187---188 189## Deployment Options190 191> **Important**: Server Mode requires **persistent file system** storage because published sites are written to `/public/deployments/` and databases are stored locally. Serverless platforms like Vercel, Netlify, and Cloudflare Workers **will not work** for Server Mode.192 193### Option 1: Desktop App (Easiest)194 195**Why**: Zero setup — download, install, run. The desktop app bundles the full server with SQLite, so you get publishing and sync without running a server.196 197**Pricing**: Free198 199**Steps:**200 2011. Download the installer for your platform from [GitHub Releases](https://github.com/o-stahl/osw-studio/releases)2022. Install and launch — authentication is bypassed for the single local user2033. Published sites are served locally at `http://localhost:3000/deployments/{id}/`204 205**Best for**: Personal use, local development, and evaluating Server Mode features without provisioning a server.206 207---208 209### Option 2: Railway (Recommended for Hosting)210 211**Why**: Simple setup, persistent storage, usage-based pricing212 213**Pricing**: $5/month minimum (includes $5 in usage credits). Free trial: 30 days with $5 credits.214 215**Steps:**216 2171. **Create Railway Account:**218   - Go to https://railway.app219   - Sign up with GitHub220 2212. **New Project:**222   - Click "New Project"223   - Select "Deploy from GitHub repo"224   - Choose your OSW Studio fork225 2263. **Configure Variables:**227   - Go to project variables228   - Add:229     ```230     NEXT_PUBLIC_SERVER_MODE=true231     SESSION_SECRET=<generate>232     NEXT_PUBLIC_APP_URL=${{ RAILWAY_PUBLIC_DOMAIN }}233     ```234 2354. **Deploy:**236   - Railway auto-deploys on push237   - Access at: `https://your-project.up.railway.app`238 239---240 241### Option 3: VPS (Full Control)242 243**Why**: Complete control, custom domains, lowest cost at scale244 245**Requirements:**246- Ubuntu 22.04+ server (Hetzner, DigitalOcean, Linode, etc.)247- SSH access248- Domain (optional, but recommended for SSL)249 250**Quick Overview:**2511. Create server with SSH key and firewall (ports 22, 80, 443 only)2522. Create non-root user, harden SSH, install fail2ban2533. Install Node.js via nvm, clone repo, configure environment2544. Build app and run with PM22555. Setup Nginx reverse proxy2566. Add SSL with certbot257 258**See the full guide:** **[VPS Deployment Guide](?doc=vps-deployment)** — includes security hardening, swap setup, PM2 auto-start, and detailed step-by-step instructions.259 260---261 262## Environment Variables263 264| Variable | Required | Description |265|----------|----------|-------------|266| `NEXT_PUBLIC_SERVER_MODE` | Yes | Set to `true` to enable Server Mode |267| `SESSION_SECRET` | Yes | Random string for JWT signing |268| `ADMIN_PASSWORD` | No | Bootstrap only. Used for initial setup when no user accounts exist. Once the first account is created via `/admin/register`, this is ignored. New installs can skip this entirely. |269| `ANALYTICS_SECRET` | No | Secret for analytics API |270| `SECRETS_ENCRYPTION_KEY` | No | 256-bit key for encrypting secrets |271| `SECURE_COOKIES` | No | Set to `false` to allow insecure cookies (pre-SSL only) |272| `NEXT_PUBLIC_APP_URL` | No | Base URL for SEO/sitemaps |273| `REGISTRATION_MODE` | No | `open` to allow user self-registration, `closed` (default) for admin-only provisioning |274| `NEXT_PUBLIC_REGISTRATION_MODE` | No | Client-side mirror of `REGISTRATION_MODE` |275| `INSTANCE_API_KEY` | No | Shared secret for machine-to-machine admin API auth |276| `INSTANCE_ID` | No | Instance identifier for multi-instance setups |277 278For multitenancy details, see **[Multitenancy](?doc=multitenancy)**.279 280---281 282## Troubleshooting283 284### Database Issues285 286**Symptoms**: "Failed to initialize database"287 288**Solutions**:2891. Check write permissions on `data/` directory2902. Ensure disk space is available2913. Check file system supports SQLite (most do)2924. Try deleting `data/osws.sqlite` and restarting (loses data)293 294### Migration Failures295 296**Symptoms**: Tables not created, "relation does not exist"297 298**Solutions**:2991. Migrations run automatically on first request3002. Check terminal logs for errors3013. Restart the server to trigger migrations302 303### Authentication Issues304 305**Symptoms**: Can't login to /admin306 307**Solutions**:3081. If no users exist yet, visit `/admin` to create the admin account3092. Clear browser cookies and try again3103. Try incognito mode3114. Check `SESSION_SECRET` is set in .env3125. If you've forgotten your password, delete `data/system.sqlite` and restart to re-create the admin account (workspace data is preserved)313 314### Performance Issues315 316**Symptoms**: Slow site loads, high memory317 318**Solutions**:3191. Optimize published sites:320   - Compress images321   - Minify CSS/JS322   - Use CDN for libraries3232. Monitor server resources:324   ```bash325   htop  # or top326   df -h  # disk space327   free -m  # memory328   ```3293. Scale server resources (RAM/CPU)3304. Add caching (Nginx cache)331 332---333 334## Next Steps335 336- **[Deployment Publishing](?doc=site-publishing)** - Publish deployments with analytics, SEO, compliance337- **[Backend](?doc=backend-features)** - Database, edge functions, secrets338- **[FAQ](?doc=faq)** - Common Server Mode questions339- **[Troubleshooting](?doc=troubleshooting)** - Fix common issues340