Laravel Vapor

Laravel Vapor orchestrates serverless computing based on AWS Lambda.

Documentation

Apart from the following documentation please also refer to the official documentation, which contains an approachable video series.

Corresponding AWS Services

On behalf of the user Laravel Vapor configures several AWS services. Their correspondence to the respective Vapor resources is as follows:

• Projects
  • Assets: CloudFront
  • Environments: Lambda
  • HTTP: API Gateway
  • Logs: CloudWatch
  • Mails: SES
  • OCI Images: ECR
  • Queues: SQS
  • Storage: S3
• Resources
  • Networks: CloudFormation
    • NAT Gateways: VPC
    • Load Balancers: EC2
    • Jumpboxes: EC2
  • Databases: RDS
  • Caches: DynamoDB or EC2
  • Domains: Route 53
    • DNS Records: Route 53
    • Certificates: ACM

PTR Integration

A PHAR of the Vapor CLI is included with our shared OCI images. It can be invoked using bin/ptr exec vapor.

PTR’s deploy task also invokes Vapor for all environments which end with the name of the current branch.

For example the following environments would be matched by the branch name master:

• bluecloud-dbb-main-master
• bluecloud-dsb-main-master

This allows for multiple instances per branch which can be useful for separate installations of different customers of the same production.

HOWTOs

Manage Team

The company’s Laravel Vapor resources are owned by a team. The team is configured with AWS access and billing information. It is managed by the user with the mail address issues@big5.de. The credentials for that account can be found in Bitwarden. However each person should use their individual account to access Laravel Vapor. In order to be invited to the team a person needs to create their account first.

Login

Log into your Vapor account.

bin/ptr exec vapor login

When asked whether to link a cloud provider answer with “no”. All resources are owned by the team and therefore, its configured cloud provider is used. A personal one is not required.

Then make sure to switch to the team “BIG 5 Concepts GmbH”.

bin/ptr exec vapor team:switch

This ensures that all resources created in the future will be associated with the team and not your personal account.

When logging into the web interface also make sure that you’ve selected the correct team at the top of the left menu.

Configure a Project for Vapor

Before starting to configure Vapor ensure that the newest version of the branch corresponding to the Laravel major version used by your application was merged from the repository laravel-docker.

git remote add --no-tags laravel-docker git@bitbucket.org:big5concepts-ondemand/laravel-docker.git
git fetch laravel-docker
git merge laravel-docker/$LARAVEL_MAJOR_VERSION

Also ensure that the OCI images are up to date.

bin/ptr build

Install the required dependencies, publish their assets and configuration and initialize the Laravel Vapor configuration.

bin/ptr exec composer require --update-with-dependencies laravel/vapor-{cli,core,ui}
bin/ptr exec yarn add laravel-vapor
bin/ptr clear
bin/ptr exec composer exec -- php artisan vapor-ui:install
bin/ptr exec composer exec -- php artisan vendor:publish --tag=vapor-ui-config
bin/ptr exec vapor init

On initialization Vapor automatically creates two default environments. Since they are not necessary for our use case we will remove them using the following commands.

bin/ptr exec vapor env:delete production
sleep 60
bin/ptr exec vapor env:delete staging

Create a new Environment

Each project may have multiple environments. Their names should follow the usual scheme. Create a new environment (named $ENVIRONMENT in the following) using the following commands.

Environment

bin/ptr exec vapor env --docker $ENVIRONMENT
sed -i '/^.env./d' .gitignore
sed -En -e 's/^ARG php=([0-9]+)\.([0-9]+)$/FROM laravelphp\/vapor:php\1\2/p' -e '$aCOPY . /var/task' < Dockerfile > $ENVIRONMENT.Dockerfile

Then edit the configuration for the environment.

${EDITOR:-vi} vapor.yml

The easiest way is to just copy-paste the configuration of another already existing environment and adjust its name as well as its cache, database, domain and storage options when present.

Database

You probably also want to create a matching database for the environment.

bin/ptr exec vapor database --public $ENVIRONMENT

Environment Variables

To configure the application you may set environment variables. Laravel Vapor already automatically injects appropriate ones to make the AWS services work. However it doesn’t activate SES by default. To do that download the environment variables and remove the MAIL_*=log variables by running the following commands:

bin/ptr exec vapor env:pull $ENVIRONMENT
sed -i '/^MAIL_\(DRIVER\|MAILER\)=log$/d' .env.$ENVIRONMENT

Now you may manually edit further environment variables.

${EDITOR:-vi} .env.$ENVIRONMENT

When you’re done upload the update environment variables.

bin/ptr exec vapor env:push --no-interaction $ENVIRONMENT

Secrets

You may also configure secrets.

bin/ptr exec vapor secret

Final Steps

Finally commit and deploy your changes.

git commit -- $ENVIRONMENT.Dockerfile vapor.yml
bin/ptr exec vapor deploy $ENVIRONMENT

The first deployment of an application might take a bit longer due to the need for DNS settings to propagate.

After the application was deployed your can execute additional commands to initialize it. For example you could seed the database as follows:

bin/ptr exec vapor command --command='db:seed DsbSeeder' $ENVIRONMENT

Configure a Domain

By default Laravel Vapor a sets up a randomly created vanity domain for the application. This is fine for non-production use. But for production you probably want to use a nice domain.

You may either use a pre-existing domain or register a new one on AWS or any other provider. After that create a DNS zone for the domain:

bin/ptr exec zone $DOMAIN

After the zone has been created you need to set your domain’s nameserver to the ones the of the zone. You need to do this at the provider where you registered the domain.

After the nameserver settings have been updated you can create a certificate and configure the domain in the manifest.

bin/ptr exec cert $DOMAIN
${EDITOR:-vi} vapor.yml

Optionally you can now remove the vanity domain.

bin/ptr exec vapor vanity-domain:delete $ENVIRONMENT

Finally redeploy the application.

bin/ptr exec vapor deploy $ENVIRONMENT