Laravel environments

Bref lets you deploy the same application multiple times in separate environments, for example dev, staging, prod, or one environment per pull request.

The Bref Cloud CLI calls them environments (bref deploy --env=prod), while the serverless CLI calls them stages (serverless deploy --stage=prod). This is just a vocabulary difference.

Laravel also has an application environment, configured with the APP_ENV environment variable. These concepts are related, but they do not have to use the exact same name.

bref deploy --env=prod

In serverless.yml, the deployment environment is available as ${sls:stage} for both CLIs:

serverless.yml

provider:
    environment:
        APP_ENV: ${param:appEnv}
 
params:
    default:
        appEnv: ${sls:stage}
    prod:
        appEnv: production

In this example, most deployment environments use their name as APP_ENV, but the prod deployment environment is mapped to Laravel's production environment.

⚠️

Laravel treats production as the production environment. For example, app()->isProduction() returns true only when APP_ENV=production.

Using prod as a deployment environment name is common because it is short and appears in AWS resource names such as Lambda functions and CloudFormation stacks. If you use prod, map it to APP_ENV=production for Laravel.

Configure each environment

Parameters are a convenient way to configure values that change between deployment environments.

You can use them for Laravel environment variables:

serverless.yml

provider:
    environment:
        APP_ENV: ${param:appEnv}
        APP_DEBUG: ${param:debug}
 
        DB_CONNECTION: mysql
        DB_HOST: ${param:databaseHost}
        DB_DATABASE: ${param:databaseName}
        DB_USERNAME: root
        DB_PASSWORD: ${ssm:/my-app/${sls:stage}/db-password}
 
params:
    default:
        appEnv: ${sls:stage}
        debug: 0
        databaseHost: shared-dev.cluster-abc123.eu-west-1.rds.amazonaws.com
        databaseName: my_app_dev
 
    staging:
        databaseName: my_app_staging
 
    prod:
        appEnv: production
        databaseHost: prod.cluster-def456.eu-west-1.rds.amazonaws.com
        databaseName: my_app_prod

Parameters can also configure non-environment-variable values in serverless.yml, such as custom domains, certificates, VPC settings, or existing resource names:

serverless.yml

provider:
    vpc: ${param:vpc, ''}
 
constructs:
    website:
        type: server-side-website
        domain: ${param:domain, ''}
        certificate: ${param:certificate, ''}
 
params:
    default:
        domain: ''
        certificate: ''
    prod:
        domain: example.com
        certificate: arn:aws:acm:us-east-1:123456789012:certificate/...
        vpc:
            securityGroupIds:
                - sg-0123456789abcdef0
            subnetIds:
                - subnet-0123456789abcdef0
                - subnet-abcdef0123456789

This keeps the configuration in one file while making the differences between environments explicit.

Production isolation

It is possible, and often recommended, to deploy production in a separate AWS account from development and staging environments.

This gives production stronger isolation:

production data and resources are separated from test environments
permissions can be stricter for production deployments
experimental environments are less likely to affect production quotas or resources

If you use Bref Cloud, you can connect multiple AWS accounts and deploy each environment to the right account without dealing with multiple credentials.

Reusing resources

Each deployment environment creates its own Lambda functions and CloudFormation stack. However, not every environment needs its own database, VPC, NAT gateway, or other expensive infrastructure.

For staging, development, and preview environments, you can reuse shared resources by referencing them through parameters:

serverless.yml

params:
    default:
        databaseHost: shared-dev.cluster-abc123.eu-west-1.rds.amazonaws.com
        vpc:
            securityGroupIds:
                - sg-shareddev
            subnetIds:
                - subnet-shareddev-a
                - subnet-shareddev-b
 
    prod:
        databaseHost: prod.cluster-def456.eu-west-1.rds.amazonaws.com
        vpc:
            securityGroupIds:
                - sg-production
            subnetIds:
                - subnet-production-a
                - subnet-production-b

Preview environments can also share a development database cluster while using a different database name, schema, or prefix per environment.

This approach reduces AWS costs and makes deployments faster because Serverless does not need to create a full VPC and database for every temporary environment.

Getting started File Storage