docs/SELF_HOSTED_DOMAINS.md

# Self-Hosted Domain Routing

Guide for OSW Studio operators running their own instances.

## Deployment Serving

Published deployments are served by Node.js route handlers by default. For better performance, set `STATIC_PROXY=true` in `.env` and use a reverse proxy (e.g., Caddy) to serve deployment files directly. With this setup, deployment requests bypass Node.js entirely.

When `STATIC_PROXY=true`, publishing or deleting a deployment with a custom domain automatically regenerates the proxy config and reloads it.

## Custom Domains

Users can set a custom domain in Deployment Settings and publish. The instance exposes a domain resolution API for proxy integration:

```
GET /api/resolve-domain?host=sweetcandies.com     → { deploymentId, path }
GET /api/resolve-domain?domain=sweetcandies.com   → 200 or 404 (for on-demand TLS verification)
GET /api/resolve-domain?list=true                  → { domains: [...] } (all registered domains)
```

### User Setup

1. Enter their domain in Deployment Settings
2. Publish the deployment
3. Add a DNS A record pointing to your server's IP
4. Wait for DNS propagation and SSL provisioning

### Notes

- Deployments published with a custom domain use root-relative asset paths. The direct URL at `/deployments/{id}/` will have broken assets — access via the custom domain instead.
- The domain is registered in the routing table on publish. If a domain is removed and republished, the routing entry is cleared.