Deployment
Bref recommends using the Serverless framework to deploy your serverless application. This page will show you how.
Deploying manually
To deploy an application configured with serverless.yml
to AWS, run:
serverless deploy
A
.serverless/
directory will be created. You can add it to.gitignore
.Want to get an overview of your deployed application? Check out the Bref Dashboard.
Deploying for production
In the previous step, we deployed the project installed on your machine. This is probably a development version.
For production, we usually don't want to deploy:
- dev dependencies
- dev configuration
- etc.
Instead, let's remove development dependencies and optimize Composer's autoloader for production:
composer install --prefer-dist --optimize-autoloader --no-dev
Now is also the best time to configure your project for production, as well as build any file cache if necessary.
Once your project is ready, you can deploy via the following command:
serverless deploy
Stages
Serverless Framework has a concept of "stages", another name for "environments". We can deploy the same application multiple times in completely separated environments:
serverless deploy --stage=prod
The default stage is dev
. The example above deploys a prod
stage.
Each stage is a separate CloudFormation stack, with completely separate AWS resources (Lambda functions, logs, permissions, etc.). All AWS resources are prefixed with the service
and stage name (for example myapp-dev-api
), which avoids any collision between stages.
It is possible to deploy different stages in different AWS accounts (to lock down permissions), and to deploy one stage per git branch, pull request, or even developer in the team.
Automating deployments
If you are using Gitlab CI, Travis CI, CircleCI or any tool of the sort you will want to automate the deployment to something like this:
# Install Composer dependencies optimized for production
composer install --prefer-dist --optimize-autoloader --no-dev
# Perform extra tasks for your framework of choice
# (e.g. generate the framework cache)
# [...]
# Deploy
serverless deploy
That will also mean creating AWS access keys so that the continuous integration is allowed to deploy.
You can find configuration examples for CI/CD tools in the Bref examples repository.
Regions
AWS runs applications in different regions. The default region is us-east-1
(North Virginia, USA).
If you want to use a different region (for example to host your application closer to your visitors) you can configure it in your serverless.yml
:
provider:
region: eu-west-1 # Ireland, Europe
...
If you are a first time user, using the
us-east-1
region (the default region) is recommended for the first projects. It simplifies commands and avoids a lot of mistakes when discovering AWS.
Deletion
To delete the whole application you can run:
serverless remove
How it works
CloudFormation stacks
The serverless deploy
command will deploy everything via a CloudFormation stack. A stack is nothing more than a bunch of things that compose an application:
- lambda functions
- S3 buckets
- databases
Stacks make it easy to group those resources together: the whole stack is updated at once on deployments, and if you delete the stack all the resources inside are deleted together too. Clean and simple.
All of this is great except CloudFormation configuration is complex. This is where Serverless helps.
serverless.yml
The Serverless framework offers a simple configuration format. This is what you are using if you use Bref. That configuration is written in your project in a serverless.yml
file.
You can learn more about that configuration format here.
Learn more
Read more about serverless deploy
in the official documentation.