Spaces:

otst
/

osw-studio

Running

App Files Files Community

osw-studio / docs /SITE_PUBLISHING.md

otst

sites -> deployments rename, project-scoped backend features, split deployment databases, unified templates

03eeded 16 days ago

preview code

raw

history blame contribute delete

9.94 kB

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

Right-click on a project card
Select "Create Deployment"
Enter deployment name
Click "Create Deployment"

From Deployments View

Click "+ New Deployment" button
Select source project
Enter deployment details
Click "Create Deployment"

Publishing Workflow

Create/edit deployment settings
Click "Save & Close"
Click "Publish Now" (or right-click deployment → Publish)
Static builder runs:
- Loads project files from server
- Compiles Handlebars templates (partials from /templates/, context from /data.json)
- 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}/
Site is live!

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 (Advanced)

Configure a custom domain for your published deployment.

Overview

By default, deployments are available at:

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

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/deployments/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 deployment
    location / {
        proxy_pass https://your-osw-instance.com/deployments/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/deployments/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 Deployments → Your Deployment → 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 deployment path
    rewrite * /deployments/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: Deployment not building, empty /public/deployments/

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

Deployment Not Updating After Republish

Symptoms: Changes not showing on published site

Solutions:

Hard refresh browser (Ctrl+Shift+R)
Check settingsVersion vs lastPublishedVersion in deployment 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 deployment path:

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

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

Next Steps

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