Merge pull request #2187 from brefphp/aws-projects

Documentation: AWS projects and missing install steps in the Laravel guides

Author: mnapoli

docs/cloud-getting-started.mdx

@@ -9,7 +9,7 @@ Bref Cloud is a service that makes it easy to deploy and monitor serverless PHP
 
 To get started, [create a free Bref Cloud account](https://bref.cloud/register).
 
-You will be guided through the process of creating an AWS account (if needed) and connecting it to Bref Cloud.
+You will be guided through the process of creating an AWS account (if needed) and connecting it to Bref Cloud. If you create a new AWS account, use the [AWS sign-up form](https://signin.aws.amazon.com/signup?request_type=register) (*Sign up for AWS (advanced)*). Do not use *Sign up for AWS (new)*: it creates an [AWS project](./setup.mdx#aws-projects), a restricted AWS account that is not suited for production applications, and that Bref Cloud cannot connect to.
 
 ## Installing the CLI
 

docs/laravel/file-storage.mdx

@@ -9,13 +9,19 @@ When running on Lambda, you will need to use the **`s3` adapter** to store files
 
 The easiest way to set up S3 storage is using [Serverless Lift](https://github.com/getlift/lift):
 
-First install the Lift plugin:
+First install the Flysystem S3 adapter, which Laravel's `s3` disk requires (without it, any file operation fails with `Class "League\Flysystem\AwsS3V3\PortableVisibilityConverter" not found`):
 
 ```bash
-serverless plugin install -n serverless-lift
+composer require league/flysystem-aws-s3-v3
 ```
 
-Then use [the `storage` construct](https://github.com/getlift/lift/blob/master/docs/storage.md) in `serverless.yml`:
+Then install the Lift plugin:
+
+```bash
+npm install --save-dev serverless-lift
+```
+
+Enable it in the `plugins` section of `serverless.yml` (in the file generated for Laravel, uncomment the `- serverless-lift` line), then use [the `storage` construct](https://github.com/getlift/lift/blob/master/docs/storage.md) in `serverless.yml`:
 
 ```yaml filename="serverless.yml"
 provider:

docs/laravel/queues.mdx

@@ -14,10 +14,10 @@ To make things simpler, we will use the [Serverless Lift](https://github.com/get
 First install the Lift plugin:
 
 ```bash
-serverless plugin install -n serverless-lift
+npm install --save-dev serverless-lift
 ```
 
-Then use [the Queue construct](https://github.com/getlift/lift/blob/master/docs/queue.md) in `serverless.yml`:
+Enable it in the `plugins` section of `serverless.yml` (in the file generated for Laravel, uncomment the `- serverless-lift` line), then use [the Queue construct](https://github.com/getlift/lift/blob/master/docs/queue.md) in `serverless.yml`:
 
 ```yml filename="serverless.yml"
 provider:
@@ -60,6 +60,8 @@ When integrated with AWS Lambda, SQS has a built-in retry mechanism and storage
 
 Instead, "Bref for Laravel" makes all the features of Laravel Queues work out of the box, just like on any server. Read more in [the Laravel Queues documentation](https://laravel.com/docs/queues).
 
+Failed jobs are stored in the `failed_jobs` database table, like on any server. If your application has no database, set `QUEUE_FAILED_DRIVER: 'null'` in `provider.environment`: failed jobs are still logged, but not stored. Otherwise, storing the failed job fails as well, for example with `Database file at path [/var/task/database/database.sqlite] does not exist`.
+
 > [!TIP]
 >
 > The "Bref-Laravel bridge" v1 used to do the opposite. We changed that behavior in Bref v2 in order to make the experience smoother for Laravel users.

docs/setup/index.mdx

@@ -35,11 +35,15 @@ To use Bref Cloud, you will need a [Bref Cloud](/cloud) account, an AWS account,
 
     Bref Cloud deploys your applications to your AWS account.
 
-    To create an AWS account, **go to [aws.amazon.com](https://aws.amazon.com/) and click *Sign up***. Bref Cloud will guide you through the process of creating an AWS account and connecting it to Bref Cloud.
+    To create an AWS account, **use the [AWS sign-up form](https://signin.aws.amazon.com/signup?request_type=register)** (*Sign up for AWS (advanced)*, the form that asks for a root user email address and an AWS account name). Bref Cloud will guide you through the process of creating an AWS account and connecting it to Bref Cloud.
+
+    > [!WARNING]
+    >
+    > Do not use *Sign up for AWS (new)*, where you log in with Google, GitHub, Apple or Amazon. It creates an "AWS project": a restricted AWS account that is not suited for production applications, and that Bref Cloud cannot connect to. [Learn why](#aws-projects).
 
     If you want to learn more about how Bref Cloud connects securely to your AWS account, read the ["Security" documentation](./cloud-security.mdx).
 
-    AWS has a generous free tier that will usually allow you to deploy your first serverless applications for free.
+    AWS has a generous free tier that will usually allow you to deploy your first serverless applications for free. If you choose the *Free plan* when signing up, AWS closes the account after 6 months (or once the free credits are used) unless you upgrade it to the *Paid plan*: upgrade before running production applications.
 
     ### Bref CLI
 
@@ -77,9 +81,13 @@ To use Bref with the Serverless CLI, you will need an AWS account, the `serverle
 
     ### AWS account
 
-    Bref deploys your applications to your AWS account. To create one, **go to [aws.amazon.com](https://aws.amazon.com/) and click *Sign up***.
+    Bref deploys your applications to your AWS account. To create one, **use the [AWS sign-up form](https://signin.aws.amazon.com/signup?request_type=register)** (*Sign up for AWS (advanced)*, the form that asks for a root user email address and an AWS account name).
 
-    AWS has a generous free tier that will usually allow you to deploy your first serverless applications for free.
+    > [!WARNING]
+    >
+    > Do not use *Sign up for AWS (new)*, where you log in with Google, GitHub, Apple or Amazon. It creates an "AWS project": a restricted AWS account that is not suited for production applications. [Learn why](#aws-projects).
+
+    AWS has a generous free tier that will usually allow you to deploy your first serverless applications for free. If you choose the *Free plan* when signing up, AWS closes the account after 6 months (or once the free credits are used) unless you upgrade it to the *Paid plan*: upgrade before running production applications.
 
     ### Serverless CLI
 
@@ -100,6 +108,8 @@ To use Bref with the Serverless CLI, you will need an AWS account, the `serverle
     > [!NOTE]
     >
     > If you have already set up AWS credentials on your machine (for example if you use the `aws` CLI), you can skip this step.
+    >
+    > If those credentials are stored in a named profile (for example created with `aws login --profile my-project`), select it with the `AWS_PROFILE` environment variable (`export AWS_PROFILE=my-project`) or with the `--aws-profile` option of the `serverless` CLI. Otherwise, `serverless deploy` fails with `AWS provider credentials not found`.
 
     - [Create AWS access keys](./setup/aws-keys.mdx)
 
@@ -132,3 +142,34 @@ That's it, you're ready to use Bref with the Serverless CLI!
 >
 > Bref is compatible with PHP 8.2 or greater.
 > If you are using PHP 8.0 or 8.1, Bref v2 (previous major version) will be installed instead.
+
+## AWS projects
+
+**Do not use AWS projects: create AWS accounts with *Sign up for AWS (advanced)*.**
+
+AWS offers two ways to sign up:
+
+- *Sign up for AWS (advanced)*: the [sign-up form](https://signin.aws.amazon.com/signup?request_type=register) that asks for a root user email address and an AWS account name. It creates a standard AWS account that you fully control.
+- *Sign up for AWS (new)*: you log in with Google, GitHub, Apple or Amazon, and AWS creates a "project". A project is an AWS account in an AWS Organization that AWS manages on your behalf, with restrictions that you cannot change.
+
+Projects make the first steps on AWS easier, but they do not fit how companies run applications in production. Companies run production in an AWS Organization that they control, with separate AWS accounts for production, staging and development, their own security policies, and permissions for each team (see [AWS best practices](https://docs.aws.amazon.com/whitepapers/latest/organizing-your-aws-environment/organizing-your-aws-environment.html)). In a project:
+
+- AWS manages the security policies of the organization (resource control policies and service control policies): you cannot define your own.
+- Every team member gets administrator access: permissions cannot be restricted per person or per team.
+- Services that access your AWS account through a cross-account IAM role do not work: monitoring, security or deployment services, including [Bref Cloud](/cloud). AWS denies access to projects from AWS accounts outside of their organization.
+- CI/CD pipelines cannot use OIDC federation to deploy without long-lived access keys (for example from GitHub Actions): AWS denies the creation of identity providers.
+- Applications can only run in one AWS region, chosen by AWS based on your country, and only a subset of AWS services is available.
+- With a spend limit, AWS blocks the creation of resources when the project gets close to the limit, then stops the application once the limit is reached (Lambda invocations are blocked).
+
+AWS gives the same advice: do not use *Sign up for AWS (new)* if you need your own policies, fine-grained permissions, the full set of AWS services, or if you have regulated workloads (see [Compare sign-up options](https://docs.aws.amazon.com/accounts/latest/reference/sign-up-for-aws.html)).
+
+Leaving these restrictions later requires "activating advanced features" in AWS Settings, which cannot be undone, and then removing the policies set by AWS yourself. Starting with a standard AWS account avoids that migration.
+
+### Deploying to an existing AWS project
+
+Bref Cloud cannot connect to AWS projects: AWS shows "Region United States (N. Virginia) unavailable" when creating the connection, or Bref Cloud reports that it is not authorized to assume its role.
+
+With the Serverless CLI, deployments work with the following changes:
+
+- Set `region` in `serverless.yml` to the region of your project, shown in [AWS Settings](https://settings.aws.com) (in the "Additional info" of the project). The examples in this documentation use `us-east-1`: deploying to a region other than the project's fails with an error ending with `with an explicit deny in a service control policy`.
+- AWS credentials are provided by `aws login`, in a named profile (for example `aws login --profile my-project`). Select that profile when deploying: `export AWS_PROFILE=my-project`. These sessions expire after 12 hours: run `aws login --profile my-project` again to renew them.

docs/symfony/messenger.mdx

@@ -64,10 +64,10 @@ However, instead of creating the SQS queue and the worker manually, you can use
 First install the Lift plugin:
 
 ```bash
-serverless plugin install -n serverless-lift
+npm install --save-dev serverless-lift
 ```
 
-Then use [the Queue construct](https://github.com/getlift/lift/blob/master/docs/queue.md) in `serverless.yml` to create a queue and a worker:
+Add `serverless-lift` to the `plugins` section of `serverless.yml`, after `./vendor/bref/bref`. Then use [the Queue construct](https://github.com/getlift/lift/blob/master/docs/queue.md) in `serverless.yml` to create a queue and a worker:
 
 ```yml filename="serverless.yml"
 provider:

docs/use-cases/websites.mdx

@@ -36,7 +36,7 @@ While it is possible to set up CloudFront manually, the easiest approach is to u
 First install the plugin:
 
 ```bash
-serverless plugin install -n serverless-lift
+npm install --save-dev serverless-lift
 ```
 
 <Tabs items={['Laravel', 'Symfony', 'PHP']}>