Custom Domain and Automatic TLS on Dockup

A custom domain and automatic TLS setup has three separate layers: the Dockup service must be healthy, DNS must point the hostname to the platform, and the hostname must pass verification before a certificate can be issued. Treating those layers separately makes cutover predictable and keeps DNS mistakes from looking like application failures.

Dockup also gives every service a *.dockup.tech address. Keep that address available during DNS propagation so you can test the application independently from the custom hostname.

What should be ready before adding a Dockup custom domain?

Start with a service that is already running and passes its readiness gate:

dockup status production/web --json
dockup health production/web --json

Open or test the existing *.dockup.tech URL. If the application is failing there, adding a domain will not repair it. Inspect runtime logs first.

Collect the following information:

Item	Example	Why it matters
Exact target	production/web	Prevents domain attachment to the wrong service
Hostname	app.example.com	The DNS name users will visit
DNS access	Registrar or DNS provider	Required to create the record
Current TTL	300 seconds	Controls propagation and rollback speed
Application canonical URL	https://app.example.com	May affect redirects and cookies
Health route	/health	Confirms the service before cutover

Lower the existing DNS TTL in advance when replacing a live provider. Do not delete the old record until the Dockup target, application configuration, and rollback plan are known.

Review application behavior that depends on the host. Authentication callbacks, CORS allowlists, cookie domains, OAuth redirect URLs, webhook destinations, and generated absolute links may need the new HTTPS hostname.

How do you add and verify the domain?

List current domains first:

dockup domain list production/web --json

Add the hostname:

dockup domain add app.example.com production/web --json

The response provides the DNS target that must be configured. Create the indicated CNAME record at the DNS provider. Do not invent an IP address or copy a value from another service; use the target returned for this domain.

After DNS has propagated, verify it with the returned domain ID:

dockup domain verify <domainId> production/web --json

Verification proves that the public DNS record resolves as required. A failure usually means one of four things:

1. The record name is wrong.
2. The CNAME target is wrong.
3. An old conflicting A, AAAA, or CNAME record still exists.
4. Resolver caches have not reached the new value.

Check authoritative DNS rather than repeatedly removing and recreating the domain. Propagation is a distributed cache process, not a Dockup build process.

How is the HTTPS certificate issued and maintained?

Once verification succeeds, request the certificate:

dockup domain ssl <domainId> production/web --json

Dockup handles certificate issuance for the verified hostname and serves the custom domain over HTTPS. The platform manages the TLS lifecycle, so the application container does not need to store certificate files or run a certificate renewal process.

Validate the result from outside the platform:

curl -I https://app.example.com

Confirm that:

• The certificate matches the hostname.
• The response is served over HTTPS.
• Redirects do not loop.
• The application returns the expected status.
• Authentication and callback flows use the new origin.
• Static assets load without mixed-content errors.

Certificate issuance can fail even when the application itself is healthy. Keep DNS and service diagnostics separate. Use domain verify for DNS ownership and service logs for application behavior.

The zero-downtime deployments article explains the independent release readiness gate.

How do you cut traffic over without an outage?

A safe cutover keeps the old path available until the new hostname is proven.

1. Deploy and verify the Dockup service at its platform URL.
2. Add the custom domain in Dockup.
3. Create the DNS record.
4. Verify DNS.
5. Issue TLS.
6. Test HTTPS directly.
7. Update callbacks, canonical URLs, and monitoring.
8. Send a small portion of operational traffic if the DNS setup permits.
9. Observe logs and uptime.
10. Retire the old provider only after the new path is stable.

Dockup uptime checks run every minute and report response-time statistics including p95:

dockup uptime production/web --hours 24 --json

Keep independent external monitoring for critical domains. A platform probe confirms public reachability, while an external monitor verifies the user path from another system.

If the custom domain replaces a current production host, preserve a rollback record: previous DNS value, previous TTL, old provider status, and the condition that would trigger reversal.

How do extra port domains work?

A service may expose a second HTTP port for an admin UI, metrics endpoint, or another web process. Dockup can create an additional platform domain without custom DNS:

dockup port list production/web --json
dockup port add 8080 production/web --name admin --json

The returned domain routes to the selected container port. This is separate from the main custom domain.

Do not expose a port merely because a process is listening. Ask whether the endpoint has authentication, whether it contains production data, and whether it should be public at all. An internal-only admin interface should not become internet-accessible as a convenience.

Remove an obsolete port domain through the supported domain interface only after verifying that no monitor, callback, or operator workflow still uses it. Port-domain changes are mutations and appear in the audit log.

How do you troubleshoot DNS, TLS, and application errors?

Use a layer-by-layer diagnosis:

Symptom	First check	Dockup command
Domain does not resolve	DNS record and propagation	domain verify
Certificate not issued	Domain verification status	domain list, domain ssl
HTTPS works but app errors	Runtime logs	logs --json
Redirect loop	Application proxy/host settings	env list, runtime logs
Platform URL works, custom host fails	DNS/TLS layer	Domain commands
Both URLs fail	Deployment and runtime	status, build/runtime logs
Secondary port fails	Port-domain mapping and process	port list, runtime logs

Inspect service output without mixing it with DNS conclusions:

dockup logs production/web --json
dockup status production/web --json

If a recent environment change added the canonical URL, remember that it needs a redeploy:

dockup env set APP_URL=https://app.example.com \
  -s production/web \
  --json

dockup deploy production/web --wait --json

The environment variables and secrets guide covers that lifecycle.

Domain removal and rollback

Removing the Dockup association is destructive to the route, so first move or remove the public DNS record and confirm the intended replacement. Then remove the association through the supported domain interface using the exact domain ID.

Do not remove the domain during a temporary certificate or propagation incident unless the recovery plan requires it. Keeping the configuration in place allows verification to succeed when caches update.

Review mutations with:

dockup audit --search domains --json

The audit trail should show who added, verified, secured, or removed the hostname.

Production handoff checklist

A complete custom domain and automatic TLS handoff includes the service target, hostname, domain ID, DNS record type and target, verification result, certificate result, application callback changes, monitoring URL, and rollback DNS value.

Store no certificate private key in the repository or container. Dockup’s managed TLS boundary exists precisely so the application team can operate the hostname without distributing certificate material.

For every current flag, use the Dockup CLI reference. For the initial deployment before domain work, follow Git repository to production.

Plan apex and subdomain choices

A subdomain such as app.example.com is usually the simplest application hostname because DNS providers can represent it with a CNAME. An apex such as example.com may require provider-specific flattening or alias behavior. Follow the DNS target returned by Dockup and the capabilities of the authoritative DNS provider.

Choose one canonical host and redirect alternatives at the application or routing layer. Serving both www and the apex without a canonical policy can split cookies, analytics, cache entries, and search indexing.

Test certificate renewal assumptions

Managed TLS removes the need to run a renewal client inside the container, but the hostname must continue resolving correctly. A future DNS migration, proxy change, or deleted record can break validation.

Include domain status in routine reviews:

dockup domain list production/web --json
dockup uptime production/web --hours 24 --json

The custom domain and automatic TLS runbook should name the DNS owner, renewal contact, and the date of the last external certificate check. This avoids discovering ownership only when a certificate incident occurs.

Protect non-production hostnames

Staging and preview hostnames can expose unfinished features and production-shaped data. Use application authentication where required, define an indexing policy at the application layer, and restrict distribution of non-production URLs.

Search-engine directives are not access control. A protected environment still needs authentication and appropriate data handling.

Recheck after propagation

Repeat external HTTPS and callback tests after the original DNS TTL has fully elapsed.

Start with a verifiable deployment

Attach a non-critical hostname first, preserve the platform URL during propagation, and record the exact DNS value needed for rollback.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

What DNS record does a Dockup custom domain need?

Run dockup domain add and create the DNS record shown in its response. Use that returned target rather than copying a value from another service.

When can Dockup issue TLS for a custom domain?

After the hostname's DNS record passes Dockup domain verification, request certificate issuance with the documented domain ssl command.

Does my container need to store TLS certificates?

No. Dockup manages TLS for the verified custom domain, so the application container does not need certificate files or a renewal process.

Can Dockup expose an additional container port?

Yes. The port commands can create a separate auto-generated domain for an additional public port without requiring custom DNS.

What should I check when the platform URL works but the custom domain fails?

Focus on DNS records, propagation, domain verification, and certificate status. The healthy platform URL shows that the application layer is probably working.