Introduction
Domains let you manage how your site is reached on the web. All Forge sites are assigned a freeon-forge.com
domain for development. But, you can also configure your own custom domains for your sites.
Forge domains
Forge provides every site with a freeon-forge.com
domain. These vanity domains are automatically available as soon as a site is created and and receive free HTTPS encryption.
We do not recommend using on-forge.com
domains in production. They’re best for quick previews, staging environments, or testing with zero DNS configuration.
Custom domains
You can attach your own domain names to site in Forge, such asexample.com
or app.example.com
.
Each custom domain is managed separately, allowing you to create domain-specific certificates, configure www.
redirect behaviour, and choose one domain to serve as the primary domain.
Custom domains have their own Nginx configuration files and SSL certificates, so adding or removing a domain does not impact other domains on the same site.
www.
redirect types
When adding a custom domain to a site, you can decide how Forge should handle the www.
version of that domain. Options include:
- Redirect from
www.
– traffic towww.example.com
will permanently redirect toexample.com
(recommended). - Redirect to
www.
– traffic toexample.com
will permanently redirect towww.example.com
. - No redirects – traffic will only be handled for the exact domain configured.
Wildcard subdomains
Forge also supports wildcard domains such as*.example.com
, which cover all subdomains of a given domain (e.g., api.example.com
, blog.example.com
). Wildcards are useful when you need dynamic or catch-all subdomains without adding each one individually.
Allowing wildcard subdomains will still serve traffic for the apex domain (e.g., *.example.com
will still serve traffic for example.com
).
Primary domains
Each site can designate one domain as the primary domain. Changing the primary domain does not impact your additional custom domains, it is used as the “name” of the site so that it’s easily recognisable inside of Forge and on your server.Changing the primary domain updates the site’s directory name on the server. This may affect third-party integrations and custom scripts that reference the site directory.Be sure to use Forge’s pre-configured
$FORGE_SITE_PATH
and $FORGE_RELEASE_DIRECTORY
variables inside of deploy scripts to mitigate these problems.Protecting against unconfigured domains
When provisioning your server, Laravel Forge will automatically create a “catch-all” Nginx configuration for your server at/etc/nginx/sites-available/000-catch-all
.
This is a special configuration file that is used to stop domains that are not configured on your server from being served. It will respond with a special 444
status code for any request that does not match an already configured domain.
Certificates
Forge manages SSL/TLS certificates on a per-domain basis, allowing you to secure each domain individually without impacting existing domains. Certificates are required to serve traffic over HTTPS and are automatically renewed where possible. You can choose between free, automated certificates from Let’s Encrypt or provide your own custom certificate.Let’s Encrypt
Let’s Encrypt provides free SSL certificates that are recognized across all major browsers. Certificates will be configured to cover thewww.
subdomain and wildcard subdomains (if applicable) and will automatically renew within 21 days or less before expiration. Renewal will take place at a random day and time to avoid overwhelming the Let’s Encrypt servers.
If something goes wrong while renewing a certificate, Forge will notify the server owner via email.
You must have an active Forge subscription in order for your Let’s Encrypt certificates to automatically renew.
DNS-01 verification
The DNS-01 verification method validates domain ownership by creating aTXT
record containing a temporary token. Let’s Encrypt then queries your domain’s DNS records to look for this token.
Forge simplifies this system through the use of CNAME forwarding. Instead of manually creating TXT
records or providing API tokens for your chosen DNS provider, you instead create a single CNAME
record that points to a unique target such as verify-abcdef.ssl.on-forge.com
.
Let’s Encrypt will follow this CNAME
and forward requests to the unique ssl.on-forge.com
subdomain, allowing Forge to automatically manage the underlying TXT
records. This means you can use DNS-01 verification regardless of your chosen DNS provider.
DNS-01 is our recommended choice because:
- It works for all domain types, including wildcard subdomains (
*.example.com
). - It is more reliable than HTTP-01 if your site is behind a CDN, firewall, or proxy.
- Long-term maintenance is minimal: once the
CNAME
is created, it remains valid for future renewals – no DNS changes needed.
Removal of the
CNAME
verification record will cause future renewals to fail. This record must remain in place for as long as you wish to use Let’s Encrypt certificates on the domain.HTTP-01 verification
The HTTP-01 verification method validates domain ownership by serving a temporary file athttp://your-domain.com/.well-known/acme-challenge
. Let’s Encrypt then requests this file to verify control.
Your domain must resolve to your server and port 80 must be publicly accessible.
- You don’t have access to the domain’s DNS records to configure additional records.
- You have strict restrictions around DNS record targets.
- The domain points directly to Forge and you know it won’t be placed behind a CDN, proxy, or firewall later.
Custom certificates
In addition to Let’s Encrypt, Forge also lets you install your own SSL certificates. This is useful if you use a commercial certificate authority, have an organization-validation (OV) or extended-validation (EV) certificate, or need to reuse an existing certificate across multiple systems. To use a custom certificate, you’ll need to provide:- The certificate file, including any intermediate certificates to form the full chain.
- The corresponding private key.
Cloudflare “Edge” certificates
Cloudflare provides free SSL certificates to all connected domains and all their first-level subdomains. These certificates are automatically enabled on all domains and subdomains that have Cloudflare’s proxy functionality enabled. However, if you have multiple nested subdomains (e.g.,staging.api.example.com
), this universal certificate will not cover those domains and may cause an ERR_SSL_VERSION_OR_CIPHER_MISMATCH
error.
If your application requires multiple nested subdomains, we recommend you disable Cloudflare proxying and use a traditional SSL certificate for your Laravel Forge site.
Legacy sites (created prior to Oct 2025)
Sites that were created before October 2025 have a slightly different domain and SSL management system. While most of the concept are similar, there are some key differences:- There is a single Nginx configuration file for the entire site.
- All domains on a site share the same SSL certificate. Adding or removing a domain can impact other domains on the same site since the certificate must be manually reissued to cover all domains.
- The
www.
redirect type cannot be configured. All domains will redirect fromwww.
to the apex domain, unless the domain configured is a subdomain (includingwww.
) itself. - Wildcard subdomains are configured at the site level, not per-domain. This means enabling wildcard subdomains will enable them for all apex domains on the site.
Let’s Encrypt
For sites created before October 2025, Let’s Encrypt certificates are issued using the HTTP-01 verification method unless the site is using wildcard subdomains.All domains on the site must resolve to the server and port 80 must be publicly accessible for HTTP-01 verification to succeed.
Wildcard subdomain Let’s Encrypt certificates
If wildcard subdomains are enabled, the DNS-01 verification method will be used instead and you must provide API credentials for your DNS provider. Forge supports the following Let’s Encrypt wildcard DNS providers:- Cloudflare
- DNSimple
- DigitalOcean
- Linode
- OVH
- Route53
Cloudflare API token
If you are using Cloudflare to manage your DNS, your Cloudflare API token must have theZone.Zone.Read
and Zone.DNS.Edit
permissions. In addition, the token must have permissions on all zones attached to your Cloudflare account.
Route53 user policy
If you are using Route53 to manage your DNS, your IAM user must have theroute53:ChangeResourceRecordSets
permission on your domain’s hosted zone. In addition, the user must have the route53:GetChange
and route53:ListHostedZones
permissions.