Serverless Laravel - Getting started

This guide helps you run Laravel applications on AWS Lambda using Bref. These instructions are kept up to date to target the latest Laravel version.

Setup

First, follow the Setup guide to create an AWS account and install the necessary tools.

Next, in an existing Laravel project, install Bref and the Laravel-Bref package (opens in a new tab).

composer require bref/bref bref/laravel-bridge --update-with-dependencies

Then let's create a serverless.yml configuration file:

php artisan vendor:publish --tag=serverless-config

How it works

By default, the Laravel-Bref package will automatically configure Laravel to work on AWS Lambda.

If you are curious, the package will automatically:

• enable the stderr log driver, to send logs to CloudWatch (read more about logs)
• enable the cookie session driver (opens in a new tab) (if you prefer, you can configure sessions to be stored in database, DynamoDB or Redis)
• move the storage directory to /tmp (because the default storage directory is read-only on Lambda)
• adjust a few more settings (have a look at the BrefServiceProvider for details (opens in a new tab))

Deployment

We do not want to deploy "dev" caches that were generated on our machine (because paths will be different on AWS Lambda). Let's clear them before deploying:

php artisan config:clear

When running in AWS Lambda, the Laravel application will automatically cache its configuration when booting. You don't need to run php artisan config:cache before deploying.

Let's deploy now:

serverless deploy

When finished, the deploy command will show the URL of the application.

Deploying for production

At the moment, we deployed our local codebase to Lambda. When deploying for production, we probably don't want to deploy:

• development dependencies,
• our local .env file,
• or any other dev artifact.

Follow the deployment guide for more details about deploying in general.

Specifically for Laravel, Bref will automatically cache the configuration on "cold starts". This means that you don't need to run php artisan config:cache before deploying. However, if you want to improve the cold start time you can pre-generate the config cache before deploying:

php artisan config:clear && php artisan config:cache

Troubleshooting

In case your application is showing a blank page after being deployed, have a look at the logs.

Website assets

Have a look at the Website guide to learn how to deploy a website with assets.

Laravel Artisan

As you may have noticed, we define a function named "artisan" in serverless.yml. That function is using the Console runtime, which lets us run Laravel Artisan on AWS Lambda.

For example, to execute an artisan command on Lambda, run the command below:

serverless bref:cli --args="<artisan command and options>"

For example:

serverless bref:cli --args="route:list"

For more details follow the "Console" guide.

Inertia

Laravel with Inertia runs without issue, like any other website. Follow the Websites guide to learn how to deploy a Laravel with assets with Bref.