Domains & Routes Manager
The Domains & Routes manager gives you a single place to control how every hostname pointing at your server maps to a destination. You can route subdomains to installed apps, to the Cloud OS UI itself, or to any custom host:port target. Each route can optionally require a Quazzar login before the request reaches its destination.
Find it in Settings → Domains & Routes (main navigation).
Route Table
The main view lists every active route:
| Column | Description |
|---|---|
| Hostname | The domain or subdomain that triggers this rule |
| Destination | Quazzar app, OS UI, or manual target |
| SSO Gate | Whether “Require Quazzar login” is active |
| Status | Active, Pending apply, or Error |
Click any row to edit it. Changes are staged until you click Apply routes — no downtime is incurred for routes that are unaffected by the change.
Adding a Route
- Click Add route.
- Choose the hostname type:
- Subdomain of base domain — enter the subdomain prefix, e.g.
gitforgit.example.com. - Full custom domain — toggle Custom domain and type the complete FQDN.
- Subdomain of base domain — enter the subdomain prefix, e.g.
- Pick a destination:
- Quazzar app — select from the dropdown of installed apps. The upstream is resolved automatically.
- OS UI — serves the Cloud OS dashboard at this address.
- Manual upstream — enter
host:portdirectly, useful for services Quazzar did not install.
- Optionally enable Require Quazzar login (see SSO Gate below).
- Click Save, then Apply routes.
Editing and Deleting Routes
- Edit any custom route by clicking it in the table and saving your changes.
- Delete a custom route via the row action menu. The apex route (base domain → OS UI) and auto-created app routes cannot be deleted; they can only be re-pointed.
Clicking Apply routes regenerates the Caddy configuration and reloads it with zero downtime. If the apply fails (for example, because a target host is unreachable), the previous configuration is kept and an error is shown in the Status column.
Apex Domain Behavior
By default, your base domain (e.g. example.com) serves the Cloud OS dashboard. If you re-point the apex to a different destination, the UI asks you to confirm:
“Routing the apex domain away from the OS UI means this address will no longer show the dashboard. Continue?”
The PUT /api/proxy/routes/{id}?confirm=true query parameter is required for apex re-points — submitting without it returns 409 Conflict with a prompt to confirm.
SSO Gate — Require Quazzar Login
When the Require Quazzar login toggle is on for a route, Cloud OS intercepts every incoming request via Caddy’s forward_auth directive and validates the user’s session cookie against GET /api/auth/validate. Unauthenticated users are redirected to the Cloud OS login page and returned to their original URL after sign-in.
This is useful for putting internal tools (Gitea, Grafana, home-lab dashboards) behind your Quazzar account without configuring each app’s own auth system.
SSO gate applies to HTTP/HTTPS traffic only. Direct TCP access to the upstream port is not affected. Ensure your server firewall blocks the upstream port from external access if you rely on SSO gating for security.
Port-Conflict Handling
Quazzar runs Caddy on ports 80 and 443. If another process (nginx, Apache, Caddy from a previous install) already holds those ports when you first configure routing, Cloud OS detects the conflicting systemd unit and presents three options:
Option A — Take Over Ports
Cloud OS stops and disables the conflicting service, then starts Caddy on 80/443. Best for servers where Quazzar is the only reverse proxy.
Use Settings → Domains & Routes → Port conflict → Take over or call POST /api/settings/proxy/takeover (admin only).
Option B — Coexist Snippet
Cloud OS generates a ready-to-paste nginx or Apache server block that front-proxies to Quazzar running on a high port (default 8443/8080). Paste the snippet into your existing web server’s configuration, reload it, and Quazzar receives traffic via the existing server.
Retrieve the snippet from Settings → Domains & Routes → Port conflict → Generate snippet, or call:
curl "http://localhost:8080/api/settings/proxy/coexist-snippet?proxy=nginx" \
-H "Authorization: Bearer <token>"Replace nginx with apache for Apache syntax.
Option C — Alternate Ports with Self-Signed Certificates
Quazzar runs on alternate ports (configurable, e.g. 8080/8443) with a self-signed TLS certificate. This is the fallback if you cannot modify the existing web server. Note that browsers will show a certificate warning until you install the self-signed cert or configure a proper certificate.
Upstream Discovery
Settings → Domains & Routes → Upstreams (or GET /api/proxy/upstreams) lists every upstream Quazzar knows about — installed apps, the OS UI endpoint, and any manual entries — so you can pick them by name rather than guessing ports.
Available Upstreams
| Type | How it appears | Notes |
|---|---|---|
| Quazzar app | App name (e.g. gitea) | Resolved from the container’s published port |
| OS UI | quazzar-ui | Always available |
| Manual | host:port you typed | Validated for reachability on save |
Troubleshooting
Route shows “Pending apply”
Click Apply routes. Routes are staged until manually applied so you can batch multiple changes.
Apply fails with “upstream unreachable”
Verify the target app is running (Apps → Installed) and that its container port is published. For manual upstreams, check the host and port are correct.
Port-conflict detection shows no service
If Quazzar cannot identify the conflicting service by name (non-systemd processes, Docker containers), use the coexist or alternate-port option and configure the front proxy manually.
Apex domain shows a blank page after update
An earlier bug caused the base domain to serve a blank page instead of the Cloud OS UI. This is fixed. If you upgraded from a version before this fix, navigate to Domains & Routes, find the apex route, and click Apply routes once to regenerate the Caddy config.
SSO gate redirects loop
This usually means the Cloud OS login page itself is behind the SSO gate. Ensure the apex route (or whichever route serves the login UI) does not have Require Quazzar login enabled.