AI AdminPanel Documentation

Domains and DNS

Services with HTTP routing use a hostname under the panel's configured domain. For example, my-app.panel.example.com can route to the application's container through Traefik. DNS resolution, proxy routing and certificate issuance are separate steps; a running container alone proves none of them.

Service domains

Open the service's Domains tab to inspect its primary hostname, routing status and SSL status. Use the edit action to change a subdomain. For a custom hostname, use Add custom domain, then create the DNS record shown by the panel at your DNS provider. The form shows a CNAME target when applicable.

Verification runs in the background. Wait for the domain status to change and inspect errors; there is no manual Verify button in this view. Check the final HTTPS URL in a browser before handing it to a customer. Removing a custom domain in the panel does not remove a manually created record at another DNS provider.

Changing a subdomain

Changing a subdomain replaces the service's container so the proxy routes the new hostname; expect a short interruption. The old hostname stops working at once. The new container keeps everything the deploy gave it: environment variables and vault values, volumes, command, healthcheck, config files, limits and, for apps behind the panel's single sign-on, the sign-on gate. A variable built from the service URL follows the new hostname. Services made of several containers cannot change their subdomain; deploy a replacement instead.

The change runs as one operation on the service, like a deploy: it does not start while another operation (deploy, reassignment, secret rotation) is running. If it is refused before the container is touched (for example a vault value cannot be read), the service keeps running on the old hostname while the Domains tab already shows the new one; fix the cause and change the subdomain again. If it fails after the old container was removed, the service shows Error and is blocked: see the next section.

If a change failed and the service is blocked

A change that fails after it started to replace the container leaves the service's operation claim "in doubt". Until that claim is cleared, every operation on the service is refused with "service operation active or awaiting reconciliation". That includes Redeploy and the job's own automatic retry, so the service does not come back by itself. The same happens when the change went through but one step's result is unknown, for example the new container could not be attached to the proxy network; the service can then be running and still blocked.

There is no button for this yet (an operator tool is tracked as AI-1061). The hosting administrator clears the claim in the panel's database, on the host. On a default install open it with docker exec -it aiadminpanel_postgresql psql -U aiadminpanel.

-- 1. Inspect. One row with state 'in_doubt' is the blocking claim.
SELECT service_id, state, owner_id, acquired_at
  FROM service_operation_claims WHERE service_id = '<service id>';

-- 2. Clear it. Only an in-doubt claim; never an 'active' one.
DELETE FROM service_operation_claims
 WHERE service_id = '<service id>' AND state = 'in_doubt';

The service ID is in the address of the service's page in the panel. Before step 2, check in the panel log that no job for this service is still running; an active row means one is, and must be left alone.

  1. Then finish the change: change the subdomain again in the Domains tab, or press Redeploy. Either rebuilds the container; a container left half-created by the failed run is cleaned up. The status returns to Running.
  2. Check the final HTTPS URL in a browser.

If you changed a subdomain before this fix

Releases before the AI-1099 fix rebuilt the container without its environment, volumes, command, healthcheck, config files and single-sign-on labels. The service either failed to start, or started like a fresh install with its data volume left on disk but not mounted, and a single-sign-on app became reachable without the gate. The panel keeps no record of past subdomain changes, so check the containers on the host:

docker ps -a --filter label=aiadminpanel.managed=true \
  --format '{{.Names}}  deployment={{.Label "aiadminpanel.deployment_id"}}  mounts={{.Mounts}}'

An affected container is named <service>_<service>_1 and shows no mounts. A healthy one is named <service>-<4 characters>_<part>_1. Go by the name: deployment= is also empty on healthy containers after a secret rotation, a reassignment or the repair below.

To repair, Redeploy the service, or after upgrading change its subdomain once more. Either rebuilds the full container and mounts the existing volume again. If Redeploy stops at pull_images with a Compose parse error, use the subdomain route. Anything the app wrote while it ran without its volume lived only inside that container and is lost at the repair; copy it out first with docker cp if you need it. Until repaired, treat a single-sign-on app as publicly reachable.

DNS and certificates

Configure the panel's DNS integration in Settings. The deploy worker can request a Cloudflare CNAME from the service hostname to the panel hostname; a DNS failure is logged and can leave the service needing manual DNS work. Without that integration, arrange the appropriate DNS records, commonly a wildcard for the service subdomains, with your hosting administrator.

Cloudflare DNS API access and Cloudflare DNS-01 certificate validation are different configuration uses. See Configuration for the installer's TLS_MODE and CF_DNS_API_TOKEN options. Keep tokens in the protected configuration system, not in examples or support messages.

Traefik requests certificates using the configured resolver. HTTP-01 requires public reachability on port 80; DNS-01 requires working DNS API access. Do not assume every custom domain uses HTTP-01 or that issuance is immediate.

Troubleshooting

  1. Compare the domain's displayed DNS target with the record at your provider.
  2. Check DNS propagation and any conflicting A, AAAA or CNAME records.
  3. Inspect the domain and SSL errors separately from application logs.
  4. Ask the hosting administrator to check Traefik's certificate errors and the configured validation method before changing routing or reinstalling anything.