osw-studio

Sleeping

App Files Files Community

osw-studio / docs /SERVER_MODE.md

otst

improve screenshot reliability, add site project swapping, sidebar version display

cc5b959 2 months ago

preview code

raw

history blame contribute delete

9.39 kB

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:

# 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

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. After login, you'll land on the Dashboard with server stats and traffic metrics.

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:

Loads that site's server features (edge functions, database schema, server functions, secrets)
Mounts them as transient files in /.server/
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:

Right-click in the File Explorer
Select Show Hidden Files
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:

Create Railway Account:
- Go to https://railway.app
- Sign up with GitHub
New Project:
- Click "New Project"
- Select "Deploy from GitHub repo"
- Choose your OSW Studio fork

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 }}

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 (Hetzner, DigitalOcean, Linode, etc.)
SSH access
Domain (optional, but recommended for SSL)

Quick Overview:

Create server with SSH key and firewall (ports 22, 80, 443 only)
Create non-root user, harden SSH, install fail2ban
Install Node.js via nvm, clone repo, configure environment
Build app and run with PM2
Setup Nginx reverse proxy
Add SSL with certbot

See the full guide: VPS Deployment Guide — includes security hardening, swap setup, PM2 auto-start, and detailed step-by-step instructions.

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:

Check write permissions on data/ directory
Ensure disk space is available
Check file system supports SQLite (most do)
Try deleting data/osws.sqlite and restarting (loses data)

Migration Failures

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

Solutions:

Migrations run automatically on first request
Check terminal logs for errors
Restart the server to trigger migrations

Authentication Issues

Symptoms: Can't login to /admin

Solutions:

Verify ADMIN_PASSWORD is set in .env

Try resetting password:

# Update .env
ADMIN_PASSWORD=new_password_here

# Restart server
pm2 restart osw-studio  # or npm run dev

Clear browser cookies
Try incognito mode
Check SESSION_SECRET is set

Performance Issues

Symptoms: Slow site loads, high memory

Solutions:

Optimize published sites:
- Compress images
- Minify CSS/JS
- Use CDN for libraries

Monitor server resources:

htop  # or top
df -h  # disk space
free -m  # memory

Scale server resources (RAM/CPU)
Add caching (Nginx cache)

Next Steps

Site Publishing - Publish sites with analytics, SEO, compliance
Server Features - Database, edge functions, secrets
FAQ - Common Server Mode questions
Troubleshooting - Fix common issues

Server Mode - Self-Hosting Guide

Overview

Browser Mode vs Server Mode

Browser Mode (Default)

Server Mode

Quick Start

1. Configure Environment

2. Start Server

3. Access Application

Server Context Integration

How It Works

The /.server/ Folder

Using Server Features with AI

Viewing the /.server/ Folder

Project Sync

How Sync Works

When to Use Manual Sync

Deployment Options

Option 1: Railway (Recommended)

Option 2: VPS (Full Control)

Environment Variables

Troubleshooting

Database Issues

Migration Failures

Authentication Issues

Performance Issues

Next Steps

The `/.server/` Folder

Viewing the `/.server/` Folder