Merge pull request #551 from brefphp/improve-deploy-docs

Improve documentation for on-boarding new users

docs/deploy.md

@@ -3,64 +3,48 @@ title: Deployment
 current_menu: deploy
 ---
 
-Bref recommends to use [the Serverless framework](https://serverless.com/) to deploy your serverless application.
+Bref recommends using [the Serverless framework](https://serverless.com/) to deploy your serverless application. This page will show you how.
 
-While you can read [the official deployment documentation](https://serverless.com/framework/docs/providers/aws/guide/deploying/) the following guide is optimized for PHP projects.
+## First deployment
 
-## How it works
+Deploy your application on your AWS account by running:
 
-### Stacks
+```bash
+serverless deploy
+```
 
-Everything is deployed through a **[CloudFormation](https://aws.amazon.com/cloudformation/) stack**. A stack is nothing more than a bunch of things that compose an application:
+🎉 congrats on creating your first serverless application!
 
-- lambda functions
-- S3 buckets
-- databases
+> A `.serverless/` directory will be created. You can add it to `.gitignore`.
+>
+> Want to get an overview of your deployed application? Launch the Bref Dashboard via the `vendor/bin/bref dashboard` command.
 
-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.
+## Deploying for production
 
-All of this is great except CloudFormation configuration is complex. This is where *Serverless* helps.
+In the previous step, we deployed the project installed on your machine. This is probably a *development version*.
 
-### `serverless.yml`
+For production, we usually don't want to deploy:
 
-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.
-
-## Deploying with Serverless
-
-### Deployment
+- dev dependencies
+- dev configuration
+- etc.
 
-Before deploying make sure your code is ready to be deployed. For example remove any development files from the project and install Composer dependencies optimized for production:
+Instead, let's remove development dependencies and optimize Composer's autoloader for production:
 
 ```bash
 composer install --prefer-dist --optimize-autoloader --no-dev
 ```
 
-> If you run this command in your local installation this might break your development setup (it will remove dev dependencies). Ideally deployment should be done in a separate directory, from scratch.
+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:
 
 ```bash
 serverless deploy
 ```
 
-A `.serverless/` directory will be created. You can add it to `.gitignore`.
-
-While you wait for your stack to be created you can check out [the CloudFormation dashboard](https://console.aws.amazon.com/cloudformation/home). Your stack will appear there.
-
-If an error occurs, the root cause will be displayed in the CLI output.
-
-Once your application is deployed, you can launch the Bref Dashboard via the `vendor/bin/bref dashboard` command. The dashboard will help you see the functions deployed, their metrics and their logs.
-
 ## Automating deployments
 
-Deploying from your machine is not perfect:
-
-- it will deploy development dependencies from Composer
-- it will deploy development configuration
-- it will deploy all the files in the project directory, even those in `.gitignore`
-
-This works fine when testing, but for a production setup it is better to automate 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:
 
 ```bash
@@ -77,6 +61,8 @@ 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](https://github.com/brefphp/examples).
+
 ## Regions
 
 AWS runs applications in different [regions](https://aws.amazon.com/about-aws/global-infrastructure/). The default region is `us-east-1` (North Virginia, USA).
@@ -89,7 +75,7 @@ provider:
     ...
 ```
 
-> If you are a first time user, using the `us-east-1` region (the default region) is *highly recommended* for the first projects. It simplifies commands and avoids a lot of mistakes when discovering AWS.
+> 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
 
@@ -99,6 +85,26 @@ 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](https://aws.amazon.com/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](environment/serverless-yml.md).
+
 ## Learn more
 
 Read more about `serverless deploy` in [the official documentation](https://serverless.com/framework/docs/providers/aws/guide/deploying/).

docs/environment/performances.md

@@ -99,7 +99,7 @@ package:
         - 'tests/**'
 ```
 
-Read more about the `package` configuration [in the serverless.yml documentation](https://serverless.com/framework/docs/providers/aws/guide/packaging#exclude--include).
+Read more about this [in the serverless.yml documentation](serverless-yml.md#exclusions).
 
 > **A note on VPC cold starts**
 >

docs/environment/serverless-yml.md

@@ -121,6 +121,25 @@ Most other Serverless plugins [are installed via `npm`](https://serverless.com/f
 
 You can find the list of [all Serverless plugins here](https://serverless.com/plugins/).
 
+## Exclusions
+
+It is possible to exclude directories from being deployed via the `package.exclude` section:
+
+```yaml
+package:
+    exclude:
+        - 'node_modules/**'
+        - 'tests/**'
+```
+
+This has the following benefits:
+
+- faster deployments
+- less risk of hitting [Lambda's size limit](https://docs.aws.amazon.com/lambda/latest/dg/limits.html)
+- [faster cold starts](performances.md)
+
+Read more about the `package` configuration [in the serverless.yml documentation](https://serverless.com/framework/docs/providers/aws/guide/packaging#exclude--include).
+
 ## Functions
 
 ```yaml

template/console/serverless.yml

@@ -16,3 +16,8 @@ functions:
         layers:
             - ${bref:layer.php-73} # PHP
             - ${bref:layer.console} # The "console" layer
+
+# Exclude files from deployment
+package:
+    exclude:
+        - 'tests/**'

template/default/serverless.yml

@@ -14,3 +14,8 @@ functions:
         description: ''
         layers:
             - ${bref:layer.php-73}
+
+# Exclude files from deployment
+package:
+    exclude:
+        - 'tests/**'

template/http/serverless.yml

@@ -18,3 +18,9 @@ functions:
         events:
             -   http: 'ANY /'
             -   http: 'ANY /{proxy+}'
+
+# Exclude files from deployment
+package:
+    exclude:
+        - 'node_modules/**'
+        - 'tests/**'