Connecting Custom Domains to Laravel Vapor Environments

Overview

While

Laravel Vapor
provides vanity URLs for every environment, moving to production requires a professional custom domain. Attaching a real domain involves more than just a DNS update; it requires a coordinated effort between the Vapor UI, your domain registrar, and your vapor.yml configuration. This process ensures your serverless infrastructure routes traffic correctly while maintaining secure, encrypted connections for your users.

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.
3 min read