Use your own domain

Updated

A custom domain is optional. Every Laravel Cloud environment gets a free laravel.cloud address after its first successful deployment, and every app installed through Scalpels works there. Add your own domain when you want a branded, stable address such as app.example.com.

Do you need one?

The Cloud address is fine for testing, staging, private tools and any deployment where its hostname does not matter. Laravel Cloud keeps serving that address after you add a custom domain.

A custom domain gives people an address you control. Laravel Cloud routes it to the same environment and automatically provisions and renews its SSL certificate.

Before you start

You need:

a domain you control;
access to its DNS records; and
a Laravel Cloud environment with a successful deployment.

You do not need to add or change an environment variable. In particular, never add APP_URL yourself. Laravel Cloud supplies the app's address, and a value you add overrides Cloud's value and prevents the app from following a later domain change.

Add the domain in Laravel Cloud

Open the environment in Laravel Cloud, open Network, and select Add domain. Cloud asks about four choices:

Wildcard support accepts every subdomain under the name, such as *.example.com. Wildcards require pre-verification unless the hostname is already proxied through Cloudflare.
Redirect behavior chooses whether Cloud redirects www.example.com to example.com, or the reverse.
Downtime preference chooses the simpler real-time path, which can have a short gap while HTTPS becomes ready, or an uninterrupted pre-verification path with extra DNS records first.
Cloudflare DNS settings tell Cloud whether Cloudflare manages the DNS and whether the hostname is already proxied through Cloudflare's network.

Cloud uses those answers to show the right records and the order in which to add them.

Point your DNS at Cloud

Copy the record type, name and value exactly as Laravel Cloud shows them. The origin record that sends traffic to Cloud is usually:

an A record when another DNS provider hosts your DNS; or
a CNAME when Cloudflare hosts your DNS, including at the root through CNAME flattening.

If you chose the uninterrupted path or enabled a wildcard, Cloud first shows ownership and SSL validation records. These may include a _cf-custom-hostname TXT record and _acme-challenge TXT or CNAME records. Keep a wildcard's DCV delegation CNAME in place so Cloud can renew the certificate.

When you use Cloudflare DNS, leave _acme-challenge DCV delegation records DNS only (grey cloud). Proxying those records blocks certificate issuance. Follow the state Cloud showed when you answered its Cloudflare questions for the origin record itself.

Verify and go live

Use Refresh in Laravel Cloud until the domain says Connected. Cloud considers it connected only after hostname ownership, SSL and origin routing are all verified.

Once it is connected, redeploy the environment once so the app picks up its new address. Then open the custom domain over HTTPS and check a sign-in flow, an email link or another generated link from the app.

What your app does automatically

The app reads its own address from Laravel Cloud. After the verified domain is connected and you redeploy, links in email, redirects and callbacks follow the custom domain. The original laravel.cloud address continues to reach the same environment.

Do not add APP_URL in the environment's variables. A manually added value takes priority over Cloud's injected value, pins the app to that address and stops this automatic change.

Capstan artifact hosting

Capstan uses two origins to keep artifact HTML away from your login cookie. Scalpels automatically assigns the environment's laravel.cloud address as the artifact render origin. You do not need a second custom domain and must not set CAPSTAN_ARTIFACT_RENDER_ORIGIN yourself.

Scalpels enables Capstan's artifact intent during installation. Artifact hosting then becomes available automatically after you add a custom domain and redeploy: the custom domain is the app origin and the existing laravel.cloud address is the isolated render origin. Without a custom domain both addresses are the same, so Capstan safely leaves artifact hosting unavailable and continues serving the rest of the app normally.

Troubleshooting

The domain is stuck verifying

Compare every DNS record with the type, name and value Laravel Cloud shows. DNS propagation can take time, and Cloud keeps retrying before it shows Timed out. For Cloudflare, make sure DCV records under _acme-challenge are DNS only.

The site loads but links point at the old address

First confirm the domain says Connected, then redeploy. Remove any manually added APP_URL; it overrides the address Cloud supplies.

The certificate is not issuing

Check the ownership and _acme-challenge validation records. A wildcard needs its DCV delegation CNAME kept permanently, and that record cannot be proxied through Cloudflare.

Removing or moving a custom domain

Unset it as the primary domain first if you made it primary, then detach or reassign it in the environment's domain settings. Redeploy afterwards so the app returns to the address Laravel Cloud now supplies. Capstan artifact hosting becomes unavailable again when its app and render origins are the same.