Domains
Learn how to manage domains in Laravel Vapor.
Introduction
When using Vapor, each environment is provided a unique vanity domain that you can use to access the environment after it is deployed. However, it’s important to keep in mind that vanity domains are intended for development purposes only and Vapor automatically adds “no-index” headers to responses from these URLs to prevent them from being indexed by search engines.
In addition, these vanity domains will continue to function even when an application is in maintenance mode, allowing you to test your environment before disabling maintenance mode and restoring general access.
While vanity domains are useful during the development process, it’s not recommended to use them for a production environment or share them with the public. Instead, it’s a best practice to use your own custom domain.
Adding Domains
You may add a domain that you own to Vapor through Vapor’s domain screen or by using the domain
CLI command. When adding a domain to Vapor, always add the root domain, even if you plan to serve your application from a subdomain:
Of course, you can review the details of your Vapor domains from the Vapor UI or using the domain:list
CLI command:
Managing DNS Records
When you add a domain to Vapor, you will be provided with nameservers that you should provide to your domain registrar’s nameserver configuration screen. This will designate Vapor as the entity managing the DNS records for the domain. This also allows Vapor to automatically add and remove DNS records to the domain as needed.
If you prefer to manage your DNS records on your own, requesting a certificate or attaching the domain to an environment will require you to manually create DNS records via your domain registrar.
Custom DNS Records
If you have chosen to allow Vapor to manage your DNS records, you can add, update, or DNS records at any time as needed. Vapor provides two ways for you to manage your DNS records: through the Vapor UI’s domain detail screen or via the Vapor CLI. To create a DNS record using the Vapor CLI, you can use the record
command:
The record
command functions as an “UPSERT” operation. If an existing record exists with the given type and name, its value will be updated to the given value. If no record exists with the given type or name, the record will be created.
To delete a record using the Vapor CLI, you can use the record:delete
command:
Requesting SSL Certificates
Before attaching a domain to an existing Vapor environment, you must have a valid SSL certificate. Vapor offers free, automatically renewing SSL certificates for your Vapor environment through AWS Certificate Manager.
Typically, users choose the “us-east-1” region for their certificate, which is the required certificate region for all environments using API Gateway 1.0. However, environments using API Gateway 2.0 or Application Load Balancers require a certificate in the same region as the project.
You can create a certificate through the Vapor UI’s domain screen or by using the cert
CLI command:
At this point, no further action is required and your certificate will be validated and issued within minutes.
If you self-manage your domain’s DNS records, Vapor will not be able to automatically update them. In this case, you can obtain the domain’s certificate CNAME record from the Vapor UI’s domain detail screen or by running the vapor record:list example.com
command. Then, you can update your DNS records at the external domain registrar accordingly.
Please note that some DNS providers will automatically append the domain name to the CNAME name. In these instances, you can remove the domain name from the CNAME name.
You can view the validation status of your certificates on the Vapor UI or by using the cert:list
CLI command:
If you want to delete an old certificate that is not attached to an environment, you can do so through the Vapor UI’s domain detail screen or by using the cert:delete
CLI command. After running the command, Vapor will prompt you to select the specific certificate you want to delete for the given domain:
Attaching Domains To Environments
Once your domain has a valid SSL certificate, you can attach your domain to your environment using the domain
configuration option in your application’s vapor.yml
file. When attaching a domain to an environment, you don’t need to include the “www” subdomain:
During deployment, Vapor will automatically configure the environment to handle requests on this domain. However, due to the nature of AWS CloudFront, custom domains often take 30-45 minutes to become fully active. So, do not worry if your custom domain is not immediately accessible after deployment.
If you self-manage your domain’s DNS records, Vapor will not be able to automatically update them. In this case, you can obtain the domain’s environment CNAME records from the Vapor UI’s domain detail screen or by running the vapor record:list example.com
command. Then, you can update your DNS records at the external domain registrar accordingly.
Multiple Domains
Vapor allows you to attach multiple domains to a single project. Before doing so, ensure you have a valid certificate for each of the domains. Then, update your application’s vapor.yml
file to include each domain:
Wildcard Subdomains
You may indicate that a domain should support wildcard subdomains as long as you have a valid certificate for the primary domain. To attach a wildcard domain to an environment, specify *
as the subdomain:
Multi-level Subdomains
Vapor provides support for multi-level subdomains - for example v1.api.example.com
. To make use of this functionality, a certificate must be requested which explicitly includes the full multi-level subdomain.
The certificate can be requested from the Vapor CLI:
It’s also possible to obtain a certificate for a multi-level subdomain from the Vapor domains dashboard by setting the multi-level subdomain as either the “Domain Name” or any of the “Alternative Names” in the “Advanced Settings” when requesting a certificate.
When the certificate has been issued, you may access your application from your multi-level subdomain by including it in the domain
section of your vapor.yml
configuration file and carrying out a full deployment from the Vapor CLI:
Wildcard certificates provided by AWS Certificate Manager can only protect single-level subdomains. As such, it is not possible to access your application via a multi-level subdomain when using only wildcard subdomains. The multi-level subdomain must be explicitly added to your vapor.yml
file.
Removing Vanity Domains
If you no longer want a vanity domain to be attached to your environment, you may remove it using the vanity-domain:delete <environment>
commmand: