brefphp · mnapoli · Oct 12, 2023 · Jul 10, 2023 · Jul 10, 2023 · Jul 10, 2023
diff --git a/docs/_meta.json b/docs/_meta.json
@@ -0,0 +1,40 @@
+{
+  "index": "What is Bref and serverless?",
+  "-- Getting started": {
+    "type": "separator",
+    "title": "Getting started"
+  },
+  "setup": "",
+  "laravel": "Laravel",
+  "symfony": "Symfony",
+  "default": "Other frameworks",
+  "-- How it works": {
+    "type": "separator",
+    "title": "How it works"
+  },
+  "runtimes": "PHP runtimes for AWS Lambda",
+  "-- Workflow": {
+    "type": "separator",
+    "title": "Workflow"
+  },
+  "deploy": "Deployment",
+  "local-development": "Local development",
+  "monitoring": "",
+  "-- Learn more": {
+    "type": "separator",
+    "title": "Learn more"
+  },
+  "environment": "Environment",
+  "use-cases": "Use cases",
+  "upgrading": "Upgrading",
+  "-- Learning": {
+    "type": "separator",
+    "title": "Learning"
+  },
+  "course": {
+    "title": "Course",
+    "href": "https://serverless-visually-explained.com/?ref=bref-menu"
+  },
+  "case-studies": "",
+  "community": ""
+}
diff --git a/docs/aws-cdk.mdx b/docs/aws-cdk.mdx
@@ -0,0 +1,34 @@
+import { RemoteContent } from 'nextra/data'
+import { buildDynamicMDX, buildDynamicMeta } from 'nextra/remote'
+
+export const getStaticProps = async ({ params }) => {
+    const token = process.env.GITHUB_TEST_REMOTE_MDX
+    const res = await fetch(
+        'https://api.github.com/repos/brefphp/constructs/contents/README.md',
+        {
+            headers: {
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+                ...(token && { Authorization: `Bearer ${token}` })
+            }
+        }
+    )
+    const page = await res.json()
+    if (!page.content) {
+        throw new Error(
+            `Error while fetch data from GitHub.\n${JSON.stringify(page, null, 4)}`
+        )
+    }
+    const content = Buffer.from(page.content, 'base64').toString('utf8');
+    return {
+        props: {
+            ...(await buildDynamicMDX(content, {
+                defaultShowCopyCode: true
+            })),
+            ...(await buildDynamicMeta())
+        },
+        revalidate: 10
+    }
+}
+
+<RemoteContent />
diff --git a/docs/case-studies.md b/docs/case-studies.md
@@ -1,9 +1,9 @@
 ---
-title: Case studies
-current_menu: case-studies
 introduction: A collection of case studies of serverless PHP applications built using Bref. Learn about performance, costs and migrations from existing projects.
 ---
 
+# Case studies
+
 This page collects case studies of serverless PHP applications built with or migrated to Bref.
 
 These help learn for real use cases about costs, performance and migration efforts.

diff --git a/docs/community.md b/docs/community.md
@@ -1,9 +1,9 @@
 ---
-title: Community
-current_menu: community
 introduction: A collection of links to places where to discuss and learn about Bref.
 ---
 
+# Community
+
 To report bugs you can head over to the [GitHub Bref repository](https://github.com/brefphp/bref).
 
 For support and general discussions, [open a GitHub discussion](https://github.com/brefphp/bref/discussions).

diff --git a/docs/default/_meta.json b/docs/default/_meta.json
@@ -0,0 +1,6 @@
+{
+  "getting-started": "",
+  "index": "Web apps on AWS Lambda",
+  "website-assets": "Website assets",
+  "console": "Console commands"
+}
diff --git a/docs/runtimes/console.md → docs/default/console.md b/docs/runtimes/console.md → docs/default/console.md
@@ -30,7 +30,7 @@ functions:
         runtime: php-81-console
 ```
 
-Behind the scenes, the `php-xx-console` runtime will deploy a Lambda function configured to use Bref's `php-81` AWS Lambda layer plus Bref's `console` layer (read more about these in the [runtimes documentation](./README.md)).
+Behind the scenes, the `php-xx-console` runtime will deploy a Lambda function configured to use Bref's `php-81` AWS Lambda layer plus Bref's `console` layer (read more about these in the [runtimes documentation](../runtimes.mdx)).
 
 ## Usage
 
@@ -99,7 +99,7 @@ aws lambda invoke \
 
 The [Bref Dashboard](https://dashboard.bref.sh/?ref=bref) also provides a convenient way to run commands via a terminal:
 
-[![Bref Dashboard terminal for Laravel](./dashboard-terminal.png)](https://dashboard.bref.sh/?ref=bref)
+[![Bref Dashboard terminal for Laravel](../runtimes/dashboard-terminal.png)](https://dashboard.bref.sh/?ref=bref)
 
 Functions using the "console" runtime are automatically detected, and colors are enabled by default for Laravel Artisan and Symfony Console.
 

diff --git a/docs/default/getting-started.mdx b/docs/default/getting-started.mdx
@@ -0,0 +1,66 @@
+import { Cards, Card } from 'nextra/components';
+// Path relative to the copy in the `website/` folder
+import { LaravelIcon } from '../../../components/icons/LaravelIcon';
+import { SymfonyIcon } from '../../../components/icons/SymfonyIcon';
+
+export const introduction = 'Run PHP serverless on AWS Lambda using Bref.';
+
+# Getting started - Bref with any framework
+
+This guide will help you deploy your first PHP application on AWS Lambda. The instructions below can be adapted to work with any framework.
+
+If you are using Laravel or Symfony, check out the dedicated guides instead:
+
+<Cards num={2}>
+    <Card icon={<LaravelIcon />} title="Get started with Laravel" arrow="true" href="/docs/laravel/getting-started" />
+    <Card icon={<SymfonyIcon />} title="Get started with Symfony" arrow="true" href="/docs/symfony/getting-started" />
+</Cards>
+
+## Setup
+
+First, **follow the [Setup guide](../setup.mdx)** to create an AWS account and install the necessary tools.
+
+Next, in an empty directory, install Bref using Composer:
+
+```bash
+composer require bref/bref
+```
+
+Make sure that the version of Bref that was installed is 1.0 or greater.
+
+Then let's start by initializing a new project by running:
+
+```bash
+vendor/bin/bref init
+```
+
+Accept all the defaults by pressing "Enter". The following files will be created in your project:
+
+- `index.php` contains the code of your application
+- `serverless.yml` contains the configuration for deploying on AWS
+
+You are free to edit the code in `index.php`. If you want to deploy an existing application, you can delete `index.php` and edit `serverless.yml` to point to your existing index file (for example it may be another file like `public/index.php`).
+
+## Deployment
+
+To deploy, let's run:
+
+```bash
+serverless deploy
+```
+
+Once the command finishes, it should print a URL like this one:
+
+```sh
+https://3pjp2yiw97.execute-api.us-east-1.amazonaws.com
+```
+
+Open this URL and you should see your application: `index.php` is running on Lambda!
+
+🎉 congrats on creating your first serverless application!
+
+To learn more about deployments, head over the [Deployment guide](../deploy.mdx).
+
+## Troubleshooting
+
+In case your application is showing a blank page after being deployed, [have a look at the logs](../environment/logs.md).
diff --git a/docs/websites.md → docs/default/website-assets.md b/docs/websites.md → docs/default/website-assets.md
@@ -10,16 +10,16 @@ next:
     title: Console commands
 ---
 
-> Before reading this article we assume that you have read [Bref's introduction](/docs/first-steps.md) and that you are familiar with [Bref's HTTP runtime](/docs/runtimes/http.md).
+> Before reading this article we assume that you have read [Bref's introduction](/docs/default/getting-started.mdx) and that you are familiar with [Bref's HTTP runtime](/docs/web-apps/index.md).
 
 ## Architectures
 
 Websites usually contain 2 parts:
 
-- PHP code, running on [AWS Lambda + API Gateway with the HTTP runtime](/docs/runtimes/http.md)
+- PHP code, running on [AWS Lambda + API Gateway with the HTTP runtime](/docs/web-apps/index.md)
 - static assets (CSS, JS…), [hosted on AWS S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html)
 
-![](websites/cloudfront.svg)
+![](../websites/cloudfront.svg)
 
 [CloudFront](https://aws.amazon.com/cloudfront/) (the AWS CDN) serves as an HTTP/HTTPS proxy.
 
@@ -68,9 +68,9 @@ You can access your website using the URL that Lift outputs at the end the deplo
 
 ### Setting up a domain name
 
-Just like in the "[Custom domains](/docs/environment/custom-domains.md)" guide, you need to register your domain in **ACM** (AWS Certificate Manager) to get an HTTPS certificate.
+Just like in the "[Custom domains](/docs/use-cases/http/custom-domains.mdx)" guide, you need to register your domain in **ACM** (AWS Certificate Manager) to get an HTTPS certificate.
 
-> If you have already set up this domain as a custom domain in API Gateway (by following the [Custom domain](/docs/environment/custom-domains.md) guide), you will need to remove it before continuing.
+> If you have already set up this domain as a custom domain in API Gateway (by following the [Custom domain](/docs/use-cases/http/custom-domains.mdx) guide), you will need to remove it before continuing.
 
 - open [this link](https://console.aws.amazon.com/acm/home?region=us-east-1#/wizard/) or manually go in the ACM Console and click "Request a new certificate" **in the `us-east-1` region** (CloudFront requires certificates from `us-east-1`)
 - add your domain name and click "Next"

diff --git a/docs/deploy.md → docs/deploy.mdx b/docs/deploy.md → docs/deploy.mdx
@@ -1,21 +1,24 @@
----
-title: Deployment
-current_menu: deploy
----
+import { Callout } from 'nextra/components';
 
-Bref recommends using [the Serverless framework](https://serverless.com/) to deploy your serverless application. This page will show you how.
+# Deployment
+
+Bref is designed out of the box to deploy using [the Serverless Framework](https://serverless.com/).
+
+Bref can also work with any other deployment tool: Terraform, CloudFormation, SAM, [AWS CDK](https://github.com/brefphp/constructs), Pulumi… However, the documentation and user experience is optimized for Serverless Framework.
 
 ## Deploying manually
 
-To deploy an application configured with `serverless.yml` to AWS, run:
+To deploy to AWS an application configured with `serverless.yml`, run:
 
 ```bash
 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](https://dashboard.bref.sh/?ref=bref).
+A `.serverless/` directory will be created. You can add it to `.gitignore`.
+
+<Callout>
+    Want to get an overview of your deployed application? Check out the [Bref Dashboard](https://dashboard.bref.sh/?ref=bref).
+</Callout>
 
 ## Deploying for production
 
@@ -57,7 +60,7 @@ It is possible to deploy different stages in different AWS accounts (to lock dow
 
 ## 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:
+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:
 
 ```bash
 # Install Composer dependencies optimized for production
@@ -87,7 +90,11 @@ provider:
     ...
 ```
 
-> 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.
+<Callout>
+    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.
+
+    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.
+</Callout>
 
 ## Deletion
 
@@ -97,23 +104,42 @@ To delete the whole application you can run:
 serverless remove
 ```
 
+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.
+
 ## 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:
+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
+- etc.
 
 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.
+All of this is great except CloudFormation configuration is complex. This is where Serverless Framework helps.
+
+### Zero-downtime deployments
+
+CloudFormation deploys using the [blue/green deployment strategy](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/bluegreen-deployments.html).
+
+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.
+
+#### Limits to blue/green deployment
+
+As soon as you introduce **asynchronous behaviors** (e.g. background jobs with SQS, event-driven microservices…) you may have in-flight messages (SQS jobs, EventBridge events…) created by the old version of your code that will be processed by the new version of your code.
+
+Code that handles asynchronous events must be able to handle messages created by older versions of the code.
+
+#### Database migrations
+
+Zero-downtime deployments mean that database migrations must run when code is running in production. That means either before or after the deployment (traffic switch) happens, and having a DB migration strategy compatible with that.
 
 ### `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.
+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).
 

diff --git a/docs/deploy/_meta.json b/docs/deploy/_meta.json
@@ -0,0 +1,3 @@
+{
+  "docker": "Deploying Docker images"
+}