Configure App Domains and SSL
Who this is for
Users who want to expose their app under a custom domain name (e.g., api.mycompany.com) with HTTPS.
How App Domains Work
By default, an app is accessible via its host port on the server's IP address (e.g., http://server-ip:8080). To serve the app at a proper domain over HTTPS, you add a domain to the app. CloudAIPilot:
- Creates an Nginx reverse proxy vhost for the domain, forwarding to the app's container port.
- Optionally provisions a Let's Encrypt SSL certificate.
Prerequisites
- App is running.
- You own a domain and can edit its DNS records.
- The domain's A record is already pointing to the server's IP address (see KB-03-03: Domain and DNS).
How to Add a Domain to an App
- Open the app detail → Domains tab.
- Click + Add Domain.
- Fill in:
| Field | Description | Required |
|---|---|---|
| Domain | The domain or subdomain (e.g., api.mycompany.com) | Yes |
| Target port | For compose apps: the host port to proxy to | Required for compose apps |
| Target service | For compose apps: the service name | Optional |
- Click Add.
CloudAIPilot creates an Nginx vhost and reloads Nginx.
How to Issue SSL for a Domain
After adding the domain:
- In the Domains tab, find the domain row.
- Click Issue SSL.
- CloudAIPilot runs Certbot for the domain.
- The domain status updates to
active(SSL provisioned) after success.
Prerequisite: DNS must already be propagated. SSL provisioning fails if the domain does not resolve to the server.
Domain Status Values
| Status | Meaning |
|---|---|
pending | SSL issuance in progress |
active | SSL is valid and configured |
expired | Certificate has expired |
none | No SSL — HTTP only |
How to Remove a Domain
- In the Domains tab, click Delete (trash icon) on the domain row.
- CloudAIPilot removes the Nginx vhost (best-effort — if the vhost file removal fails, it does not block the delete).
Compose Apps: Target Port Requirement
For compose apps with multiple services, you must specify which host port the domain should proxy to. Each service can have its own domain pointing to a different host port.
Example:
app.mycompany.com→ target port 8080 (web service)api.mycompany.com→ target port 3000 (API service)
What Success Looks Like
Visiting https://yourdomain.com in a browser shows the app running behind HTTPS. The domain row in CloudAIPilot shows SSL status active.
Common Issues and Fixes
| Issue | Likely cause | Fix |
|---|---|---|
| "DOMAIN_CONFLICT" | Domain already used by another app or site | Remove it from the other resource first. |
| "INVALID_TARGET_PORT" | Port specified doesn't match any mapped port | Verify the host port in Port Mapping matches. |
| "SSL_IN_PROGRESS" | Another SSL job is running for this domain | Wait and retry. |
| Nginx shows 502 Bad Gateway | App not running or wrong target port | Verify app is running and target port is correct. |