osw-studio

Sleeping

App Files Files Community

osw-studio / docs /SITE_PUBLISHING.md

otst

add site templates with automatic backend provisioning

07db684 3 months ago

preview code

raw

history blame contribute delete

9.64 kB

Site Publishing

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

Overview

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

Key Features:

One-click publishing - Compile and deploy instantly
Site 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 Site

From Projects View

Right-click on a project card
Select "Create Site"
Enter site name
Click "Create Site"

From Sites View

Click "+ New Site" button
Select source project
Enter site details
Click "Create Site"

Publishing Workflow

Create/edit site settings
Click "Save & Close"
Click "Publish Now" (or right-click site → Publish)
Static builder runs:
- Loads project files from server
- Compiles Handlebars templates (partials from /templates/, context from /data.json)
- Rewrites internal links to include /sites/{siteId}/ prefix
- Injects configured settings (scripts, analytics, SEO)
- Generates sitemap.xml and robots.txt
- Writes to /public/sites/{siteId}/
Site is live!

Accessing Published Sites

Default URL:

https://your-osw-instance.com/sites/{siteId}/

Clean URLs (Next.js rewrites):

/sites/{siteId}/about → /sites/{siteId}/about.html
/sites/{siteId}/blog/post → /sites/{siteId}/blog/post.html

Site Settings

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

General

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

Scripts

Add custom scripts to your site'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 site 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 site 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 Sites

Site Actions

Right-click any site card for actions:

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

Unpublish vs Delete

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

Version Tracking

Each site shows:

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

If these differ, the site has unpublished changes.

Custom Domains (Advanced)

Configure a custom domain for your published site.

Overview

By default, sites are available at:

https://your-osw-instance.com/sites/{siteId}/

With a custom domain, visitors access your site at:

https://sweetcandies.com/

Prerequisites

Domain you control
Access to DNS records
Reverse proxy (Nginx, Caddy, or Apache)
SSL certificate (Let's Encrypt recommended)

Architecture

User's Browser
    ↓
sweetcandies.com (DNS)
    ↓
Reverse Proxy (Nginx)
    ↓
your-osw-instance.com/sites/abc123/
    ↓
Static files served

Setup Steps

1. Configure DNS

Point your domain to your server's IP:

For root domain (sweetcandies.com):

Type: A
Name: @
Value: 123.45.67.89 (your server IP)
TTL: 3600

For subdomain (www.sweetcandies.com):

Type: CNAME
Name: www
Value: your-osw-instance.com
TTL: 3600

Wait for DNS propagation (usually < 1 hour, up to 48 hours).

2. Configure Reverse Proxy

Nginx Example:

server {
    listen 80;
    listen [::]:80;
    server_name sweetcandies.com www.sweetcandies.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name sweetcandies.com www.sweetcandies.com;

    # SSL certificates (Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/sweetcandies.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sweetcandies.com/privkey.pem;

    # Proxy to OSW Studio site
    location / {
        proxy_pass https://your-osw-instance.com/sites/abc123/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Rewrite location headers
        proxy_redirect https://your-osw-instance.com/sites/abc123/ /;
    }
}

Save to /etc/nginx/sites-available/sweetcandies.com

Enable:

sudo ln -s /etc/nginx/sites-available/sweetcandies.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

3. Setup SSL

sudo certbot --nginx -d sweetcandies.com -d www.sweetcandies.com

4. Configure in OSW Studio

Go to Sites → Your Site → Settings
Navigate to General tab
Enter custom domain: sweetcandies.com
Save and republish

OSW Studio will now use sweetcandies.com in:

SEO meta tags
Sitemap.xml URLs
Open Graph URLs
Canonical URLs

Caddy Example (Easier)

Caddy automatically handles HTTPS with Let's Encrypt:

sweetcandies.com, www.sweetcandies.com {
    # Rewrite all requests to site path
    rewrite * /sites/abc123{uri}

    reverse_proxy your-osw-instance.com {
        header_up Host {upstream_hostport}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

What OSW Studio Does

Stores custom domain in database
Uses it for SEO meta tags
Generates sitemap.xml with custom domain
Updates canonical URLs

What OSW Studio Doesn't Do

DNS management
Reverse proxy configuration
SSL certificate generation
Domain validation

Troubleshooting

Publishing Errors

Symptoms: Site not building, empty /public/sites/

Solutions:

Check build logs in terminal
Verify project has files synced to server
Check Handlebars syntax in templates
Verify disk permissions:
```
ls -la public/
chmod 755 public/
```
Check available disk space:
```
df -h
```

Site Not Updating After Republish

Symptoms: Changes not showing on published site

Solutions:

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

Custom Domain Not Working

Symptoms: Domain doesn't load site

Solutions:

Verify DNS is configured correctly:

dig sweetcandies.com
nslookup sweetcandies.com

Wait for DNS propagation (up to 48 hours)

Check reverse proxy configuration:

# Nginx
sudo nginx -t
sudo systemctl status nginx

# Check logs
sudo tail -f /var/log/nginx/error.log

Verify SSL certificate:
```
sudo certbot certificates
```

Test direct access to OSW site path:

https://your-osw-instance.com/sites/{siteId}/

Hard refresh browser (Ctrl+Shift+R)
Clear browser cache

Next Steps

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