Skip to content

Commit dfd834f

Browse files
mnapolimnapoli
committed
Update the deploy docs
1 parent c7ad729 commit dfd834f

1 file changed

Lines changed: 83 additions & 35 deletions

File tree

‎docs/deploy.mdx‎

Lines changed: 83 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { Callout } from 'nextra/components';
1+
import { Callout, Tab, Tabs } from 'nextra/components';
22

33
# Deployment
44

@@ -10,16 +10,21 @@ Bref can also work with any other deployment tool: Terraform, CloudFormation, SA
1010

1111
To deploy to AWS an application configured with `serverless.yml`, run:
1212

13-
```bash
14-
serverless deploy
15-
```
13+
<Tabs items={['Serverless CLI', 'Bref Cloud']}>
14+
<Tab>
15+
```bash
16+
serverless deploy
17+
```
18+
</Tab>
19+
<Tab>
20+
```bash
21+
bref deploy
22+
```
23+
</Tab>
24+
</Tabs>
1625

1726
A `.serverless/` directory will be created. You can add it to `.gitignore`.
1827

19-
<Callout>
20-
Want to get an overview of your deployed application? Check out the [Bref Dashboard](https://dashboard.bref.sh/?ref=bref).
21-
</Callout>
22-
2328
## Deploying for production
2429

2530
In the previous step, we deployed the project installed on your machine. This is probably a *development version*.
@@ -44,25 +49,54 @@ Now is also the best time to configure your project for production, as well as b
4449

4550
Once your project is ready, you can deploy via the following command:
4651

47-
```bash
48-
serverless deploy
49-
```
50-
51-
## Stages
52-
53-
Serverless Framework has a concept of "stages", another name for "environments". We can deploy the same application multiple times in completely separated environments:
52+
<Tabs items={['Serverless CLI', 'Bref Cloud']}>
53+
<Tab>
54+
```bash
55+
serverless deploy
56+
```
57+
</Tab>
58+
<Tab>
59+
```bash
60+
bref deploy
61+
```
62+
</Tab>
63+
</Tabs>
64+
65+
## Environments
66+
67+
We can deploy the same application multiple times in completely separated environments (also called "stages" by the Serverless CLI).
68+
69+
<Tabs items={['Serverless CLI', 'Bref Cloud']}>
70+
<Tab>
71+
```bash
72+
serverless deploy --stage=prod
73+
```
74+
</Tab>
75+
<Tab>
76+
```bash
77+
bref deploy --env=prod
78+
79+
# or
80+
bref deploy -e prod
81+
```
82+
</Tab>
83+
</Tabs>
84+
85+
The default environment is `dev`. The example above deploys a `prod` environment.
86+
87+
Each environment is a separate CloudFormation stack, with completely separate AWS resources (Lambda functions, logs, permissions, etc.). All AWS resources are prefixed with the `service` and environment name (for example `myapp-dev-api`), which avoids any collision between environments.
88+
89+
It is possible to deploy different environments in different AWS accounts (to lock down permissions), and to deploy one environment per git branch, pull request, or even developer in the team.
5490

55-
```bash
56-
serverless deploy --stage=prod
57-
```
91+
## Automating deployments
5892

59-
The default stage is `dev`. The example above deploys a `prod` stage.
93+
### Bref Cloud
6094

61-
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.
95+
If you are using [Bref Cloud](https://bref.sh/cloud), you can easily set up automatic deployments from CI/CD tools.
6296

63-
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.
97+
Read the [documentation on deploying with Bref Cloud](https://bref.sh/docs/deploying/deploying-with-bref-cloud.html) for more information.
6498

65-
## Automating deployments
99+
### Serverless CLI
66100

67101
If you are using GitHub Actions, Gitlab CI, CircleCI, or any tool of the sort you will want to automate the deployment to something like this:
68102

@@ -96,40 +130,54 @@ provider:
96130

97131
<Callout>
98132
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.
99-
100-
I mean really… I can't count how many times a command failed or an AWS page looked empty because I was in the wrong region.
101133
</Callout>
102134

103135
## Deletion
104136

105-
To delete the whole application you can run:
137+
You can delete a deployed environment using the `remove` command.
106138

107-
```bash
108-
serverless remove
109-
```
139+
<Tabs items={['Serverless CLI', 'Bref Cloud']}>
140+
<Tab>
141+
```bash
142+
serverless remove
143+
144+
# or remove a specific environment
145+
serverless remove --stage=prod
146+
```
147+
</Tab>
148+
<Tab>
149+
```bash
150+
bref remove
151+
152+
# or remove a specific environment
153+
bref remove --env=prod
154+
```
155+
</Tab>
156+
</Tabs>
110157

111-
Note that this command, like `serverless deploy`, is for a specific stage. If you want to delete all stages you will have to run the command once per stage.
158+
Note that this will destroy the AWS resources of a given environment.
159+
160+
If you want to delete all environments of an application, you can do so in the [Bref Cloud dashboard](https://bref.cloud). If you don't use Bref Cloud, you will need to delete each environment one by one.
112161

113162
## How it works
114163

115164
### CloudFormation stacks
116165

117-
The `serverless deploy` command will deploy everything via a **[CloudFormation](https://aws.amazon.com/cloudformation/) stack**. A "stack" is nothing more than a bunch of things that compose an application:
166+
Under the hood, Bref will deploy everything to AWS as a **[CloudFormation](https://aws.amazon.com/cloudformation/) stack**. A "stack" is nothing more than a bunch of things that compose an application:
118167

119-
- lambda functions
168+
- Lambda functions
169+
- HTTP endpoints
120170
- S3 buckets
121171
- databases
122172
- etc.
123173

124174
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.
125175

126-
All of this is great except CloudFormation configuration is complex. This is where Serverless Framework helps.
127-
128176
### Zero-downtime deployments
129177

130178
CloudFormation deploys using the [blue/green deployment strategy](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html).
131179

132-
This means that when you deploy, a new version of your code is deployed alongside the old one. Once the new version is ready, the traffic switches to the new version. If the deployment fails at any point, the traffic stays on the old version.
180+
This means that when you deploy, a new version of your code is deployed alongside the old one. Once the new version is ready, the traffic switches to the new version. If the deployment fails at any point, the traffic stays on the old version and the deployment is rolled back.
133181

134182
#### Limits to blue/green deployment
135183

@@ -149,4 +197,4 @@ You can [learn more about that configuration format here](environment/serverless
149197

150198
## Learn more
151199

152-
Read more about `serverless deploy` in [the official documentation](https://serverless.com/framework/docs/providers/aws/guide/deploying/).
200+
Read more about `serverless deploy` in [the official documentation](https://github.com/oss-serverless/serverless/blob/main/docs/guides/deploying.md).

0 commit comments

Comments
 (0)