Skip to main content

Custom domains & SSL

Every app gets a default Vessl URL (a *.shipto.id subdomain) the moment it deploys. To serve it on your own domain — app.example.com — add the domain in Vessl and point DNS at your server. Vessl issues and renews a Let's Encrypt certificate automatically; you never touch a certificate file.

How it works​

Your app sits behind the Traefik gateway that Vessl installed on your server. Traefik routes incoming requests by hostname and terminates TLS. When you add a custom domain, Vessl tells Traefik to request a certificate for that hostname over the HTTP-01 challenge and to route the domain to your app's container.

Step 1 — Point DNS at your server​

Create a DNS record at your domain registrar pointing the hostname to your server's public IP (the IP of the server the app is deployed on):

TypeName (host)Value
Aappyour.server.ip
  • For a subdomain like app.example.com, use an A record named app.
  • For an apex/root domain (example.com), use an A record on @, or an ALIAS/ANAME if your DNS provider supports it.
Find your server IP

It's shown on the server's detail page in the dashboard (the IP you provisioned it with).

Wait for DNS to propagate. Check with:

dig +short app.example.com

It should return your server's IP before you continue.

Step 2 — Add the domain in Vessl​

  1. Open your app → Domains (or the Network tab).
  2. Click Add Domain and enter the full hostname, e.g. app.example.com.
  3. Save.

Vessl adds the route and asks Traefik to obtain the certificate.

Step 3 — Wait for the certificate​

Certificate issuance is asynchronous and uses the HTTP-01 challenge: Let's Encrypt makes a request to http://app.example.com/.well-known/..., which must reach your server. This typically completes in 1–3 minutes after DNS is correct.

  • During issuance you may briefly see a default/self-signed certificate or a TLS warning — that's normal.
  • Once issued, https://app.example.com serves your app with a valid certificate, and HTTP redirects to HTTPS automatically.
Don't conclude it failed too early

If DNS only just propagated, give it a couple of minutes. Reload after a short wait before assuming something is wrong.

Renewal​

Renewal is automatic. Traefik renews the certificate well before expiry as long as the domain still points at your server — there's nothing to schedule.

Troubleshooting​

Certificate never issues / stuck on a warning The HTTP-01 challenge can't reach your server. Check, in order:

  1. DNS — dig +short app.example.com returns your server's IP (not a proxy, not the old host).
  2. Port 80 open — the challenge uses HTTP. Your server firewall must allow inbound 80 (Vessl's provisioning opens it; a cloud-provider security group might still block it).
  3. Not proxied — if you use Cloudflare, set the record to DNS only (grey cloud) until the certificate issues, or the challenge can be intercepted.

Works on the Vessl URL but not the custom domain The app is healthy; this is a routing/DNS issue, not an app issue. Re-check the DNS record host and value.

Apex domain won't resolve Many registrars don't allow a CNAME on the root. Use an A record to the server IP, or your provider's ALIAS/ANAME.