docs/CUSTOM_DOMAINS.md

# Custom Domains

## Setup (2 steps)

1. In OSW Studio, go to Deployment Settings and enter your domain (e.g., `sweetcandies.com`)
2. In your DNS provider, add an A record pointing to your OSW Studio server's IP address

That's it. The server handles SSL certificates automatically via Let's Encrypt.

## How It Works

When you publish a deployment with a custom domain:

1. OSW Studio registers the domain in its routing table
2. The reverse proxy (Caddy) intercepts requests to your domain
3. Caddy provisions an SSL certificate automatically (on-demand TLS)
4. Requests are routed to your deployment's static files
5. `/api/` paths (edge functions, analytics) pass through without rewriting

## What OSW Studio Handles

- Domain registration in the routing table
- Root-relative asset paths when a custom domain is set
- SEO meta tags, sitemaps, and canonical URLs using your domain
- Analytics origin validation for your domain

## What OSW Studio Does Not Handle

- DNS configuration (you add the A record)
- SSL certificates (Caddy handles this automatically)
- Domain purchase or registration

## For Self-Hosted Instances

Your OSW Studio instance needs a reverse proxy with TLS support. See `docs/SELF_HOSTED_DOMAINS.md` for API endpoints and proxy requirements.

## For Hosted Instances (oswstudio.com)

Custom domains are handled automatically by the platform. Just add your DNS A record.

## Troubleshooting

**Site not loading after adding DNS**
- DNS propagation can take up to 48 hours (usually minutes)
- Verify your A record: `dig sweetcandies.com` should show the server IP
- The first request may take a few seconds while the SSL certificate is provisioned

**SSL certificate not working**
- Ensure your DNS A record points directly to the server IP (not through a proxy)
- Caddy needs port 80 and 443 open for Let's Encrypt HTTP-01 challenges

**Assets loading from wrong path**
- Republish your deployment after setting the custom domain
- The asset path rewriting only takes effect on publish