docs/SITE_PUBLISHING.md

Deployment Publishing

Publish and configure deployments directly from OSW Studio in Server Mode.

---

Overview

Server Mode lets you publish static sites directly from your OSW Studio instance. Each deployment gets its own URL, configurable settings for analytics, SEO, compliance, and more.

Key Features:

• One-click publishing - Compile and deploy instantly
• Deployment settings - Scripts, CDN resources, analytics
• SEO optimization - Meta tags, Open Graph, sitemaps
• Compliance - Cookie consent, GDPR/CCPA banners
• Custom domains - Use your own domain (advanced)

---

Creating a Deployment

From Projects View

1. Right-click on a project card
2. Select "Create Deployment"
3. Enter deployment name
4. Click "Create Deployment"

From Deployments View

1. Click "+ New Deployment" button
2. Select source project
3. Enter deployment details
4. Click "Create Deployment"

---

Publishing Workflow

1. Create/edit deployment settings
2. Click "Save & Close"
3. Click "Publish Now" (or right-click deployment → Publish)
4. Static builder runs:
   • Loads project files from server
   • Compiles Handlebars templates (partials from /templates/, context from /data.json)
   • Uses pre-built bundle.js for framework runtimes (React, Preact, Svelte, Vue)
   • Rewrites internal links to include /deployments/{id}/ prefix
   • Injects configured settings (scripts, analytics, SEO)
   • Generates sitemap.xml and robots.txt
   • Writes to /public/deployments/{id}/
5. Site is live!

Note: Python and Lua projects cannot be published — they run only in the browser's WASM runtime. Use ZIP export for offline distribution instead.

Accessing Published Deployments

Default URL:

https://your-osw-instance.com/deployments/{id}/

Clean URLs (Next.js rewrites):

/deployments/{id}/about → /deployments/{id}/about.html
/deployments/{id}/blog/post → /deployments/{id}/blog/post.html

---

Deployment Settings

Access deployment settings by clicking the gear icon on any deployment card, or right-click → Settings.

General

• Deployment name - Display name for the deployment
• URL slug - Optional custom slug
• Custom domain - For advanced setups (see below)
• Under construction - Show maintenance page

Scripts

Add custom scripts to your deployment's HTML:

Head Scripts:

• Analytics code
• Meta tag generators
• Preload hints

Body Scripts:

• Chat widgets
• Tracking pixels
• Third-party integrations

Options:

• Inline or external URL
• Async/defer loading
• Enable/disable per script

CDN Resources

Load external CSS and JavaScript libraries:

• Bootstrap, Tailwind CDN
• Font Awesome, Material Icons
• jQuery, Alpine.js
• Google Fonts

Configuration:

• Resource URL
• Type (CSS or JS)
• Integrity hash (optional)
• Crossorigin setting

Analytics

Track visitors with built-in or third-party analytics:

Built-in Analytics (privacy-focused):

• No cookies required
• Basic pageview tracking
• Referrer tracking
• Privacy mode option

Third-party Providers:

• Google Analytics 4
• Google Tag Manager
• Plausible
• Custom tracking code

Enhanced Features (toggleable):

• Heatmaps
• Session recording
• Performance metrics
• Engagement tracking
• Custom events

Data Retention:

• Configurable retention periods
• Pageviews: 90 days default
• Interactions: 30 days default
• Sessions: 60 days default

SEO

Optimize your deployment for search engines:

Meta Tags:

• Title
• Description
• Keywords

Open Graph:

• OG Title
• OG Description
• OG Image

Twitter Card:

• Summary or Large Image

Advanced:

• Canonical URL
• noindex/nofollow options

Auto-generated:

• sitemap.xml
• robots.txt

Compliance

GDPR/CCPA cookie consent and privacy compliance:

Banner Settings:

• Position: Top, Bottom, or Corner
• Style: Bar, Modal, or Corner popup
• Custom message text
• Accept/Decline button text

Behavior:

• Opt-in mode (block until consent)
• Opt-out mode (allow until decline)
• Block analytics until consent

Policy Links:

• Privacy policy URL
• Cookie policy URL

---

Managing Deployments

Deployment Actions

Right-click any deployment card for actions:

Action	Description
View Live	Open published site in new tab
Settings	Configure deployment options
Republish	Rebuild and deploy
Copy Link	Copy deployment URL to clipboard
View Source	Open source project
Analytics	View deployment analytics dashboard
Capture Thumbnail	Update preview image
Unpublish	Disable deployment (keeps settings)
Delete	Permanently remove deployment

Unpublish vs Delete

• Unpublish: Disables the deployment but preserves all settings. You can re-publish later.
• Delete: Permanently removes the deployment and all its settings.

Version Tracking

Each deployment shows:

• Settings Version: Current configuration version
• Published Version: Last published version

If these differ, the deployment has unpublished changes.

---

Custom Domains

Use a custom domain (e.g., sweetcandies.com) for your published deployment. Enter the domain in Deployment Settings, add a DNS A record, and publish. See Custom Domains Guide for full details.

---

Troubleshooting

Publishing Errors

Symptoms: Deployment not building, empty /public/deployments/

Solutions:

1. Check build logs in terminal
2. Verify project has files synced to server
3. Check Handlebars syntax in templates
4. Verify disk permissions:

   ls -la public/
   chmod 755 public/
   

5. Check available disk space:

   df -h
   

Deployment Not Updating After Republish

Symptoms: Changes not showing on published site

Solutions:

1. Hard refresh browser (Ctrl+Shift+R)
2. Check settingsVersion vs lastPublishedVersion in deployment card
3. Verify "Publish" was clicked (not just "Save")
4. Check build succeeded in terminal logs
5. Inspect HTML source for changes
6. Clear CDN cache (if using one)

Custom Domain Not Working

See troubleshooting section in Custom Domains Guide.

---

Next Steps

• Backend - Database, edge functions, secrets
• Server Mode - Setup and deployment
• Troubleshooting - Fix common issues