Prerequisites

To follow this guide, you should be comfortable with the

framework and basic CLI commands. Locally, you must have

Docker

installed and running. You also need an active

Laravel Vapor

account and the vapor-cli package installed in your project.

Key Libraries & Tools

• Laravel Vapor: A serverless deployment platform for Laravel.
• Docker: The containerization engine used to build and package your environment.
• PHP Extensions: Specifically
  GMP
  or
  ImageMagick
  , which often require manual installation in custom environments.

Code Walkthrough: Customizing Your Environment

First, create a environment-specific Dockerfile at your root. If you are deploying to staging, name it staging.dockerfile.

FROM laravelphp/vapor:php74

Install the GMP extension for mathematical operations

RUN pecl install gmp && docker-php-ext-enable gmp

This file tells Vapor to use the official PHP 7.4 base image and executes a `RUN` command to install the missing extension. To verify the installation within your application, you can use a simple route check:

```php
Route::get('/check-extension', function () {
    return extension_loaded('gmp') ? 'Installed' : 'Missing';
});

Finally, trigger the build and deployment using the standard command. Vapor recognizes the Dockerfile and shifts from a zip-based upload to a container image build.

vapor deploy staging

Syntax Notes

Vapor uses a specific naming convention for Dockerfiles linked to environments. A file named production.dockerfile will only be used during a vapor deploy production run. This allows you to maintain different extension sets for local testing versus live environments.

Practical Examples

Custom runtimes are essential when your application needs to process complex images using

or handle high-precision math with

GMP

. It is also the go-to solution for legacy projects where the vendor folder alone exceeds the standard 250MB serverless limit.

Tips & Gotchas

Always remember that container builds take longer than standard zip deployments because Vapor must build and push the image to

. If your build fails, check that your local Docker daemon is running; Vapor uses your local machine's resources to build the image before pushing it to the cloud.