Connecting Custom Domains to Laravel Vapor Environments

Prerequisites

Before starting, ensure you have the following:

• A Laravel project already initialized with Vapor.
• The Vapor CLI installed locally.
• Access to your domain registrar's DNS management panel (e.g., Namecheap or GoDaddy).
• An active AWS account linked to your Vapor dashboard.

Key Libraries & Tools

• Laravel Vapor: A serverless deployment platform for Laravel powered by AWS Lambda.
• Vapor CLI: The command-line interface used to trigger deployments and manage environment configurations.
• AWS Certificate Manager (ACM): Handles SSL/TLS certificates to enable HTTPS.
• Route 53: The AWS DNS service that Vapor interacts with when managing your records.

Code Walkthrough

To link your domain, you must first register it within the Vapor UI under Resources > Domains. Once added, you need to update your project's configuration file.

Update vapor.yml

Open your vapor.yml file and add the domain key to your specific environment (usually production).

id: 12345
name: my-app
environments:
    production:
        memory: 1024
        domain: phpcast.dev

Deployment Command

After saving your configuration, push the changes to your environment using the CLI.

vapor deploy production

Syntax Notes

The domain key in vapor.yml expects a string representing the root domain or a subdomain. Vapor uses this key to determine which Amazon CloudFront distribution or API Gateway to associate with the incoming requests. Always ensure the indentation matches the YAML standard, as a misplaced space under the environment block will cause deployment errors.

The SSL Certificate Gotcha

A common hurdle during deployment is the SSL certificate requirement. Even if your application lives in a region like eu-central-1, AWS requires a certificate in the us-east-1 (N. Virginia) region for global edge services like CloudFront. You must manually request this via the Vapor UI's "Certificates" section for your domain, specifically selecting us-east-1 to avoid deployment failures.

Tips & Best Practices

• Delegate DNS: Let Vapor manage your DNS by pointing your registrar's Name Servers to the four values provided by Vapor. This automates record creation for SSL validation and deployments.
• Pre-issue Certificates: Request your SSL certificates in the Vapor UI before running your first deployment to prevent the CLI from hanging or erroring out.
• Check Propagation: DNS changes can take time. If your site doesn't load immediately after a successful deployment, use a tool like dig or an online DNS checker to verify propagation.