Documentation: AWS projects and missing install steps in the Laravel guides - #2187
Merged
Merged
Conversation
…guides AWS accounts created with "Sign up for AWS (new)" are AWS projects: Bref Cloud cannot connect to them, they are limited to one region, and their credentials come from `aws login`. The Laravel guides also missed two install steps: the Serverless Lift plugin (enabled in the published serverless.yml) and the Flysystem S3 adapter required by Laravel's s3 disk.
This was referenced Sep 26, 2026
Explain why projects do not fit production applications (AWS-managed policies, no fine-grained permissions, no cross-account integrations, no OIDC for CI/CD, one region, spend limit stopping the application), instead of presenting them as an option that only Bref Cloud cannot use.
…less.yml brefphp/laravel-bridge#212 comments out the plugin in the published serverless.yml, so the getting started no longer needs Lift. The guides that use constructs tell to uncomment it.
The docs recommend against AWS projects, the setup page covers what to change for those who use one anyway.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
I redid the onboarding from scratch: a brand new AWS account, a fresh
laravel newapp with the recommended setup (queue, S3 storage, website assets), following the docs.AWS projects
AWS now offers two ways to sign up. With "Sign up for AWS (new)", users log in with Google/GitHub/Apple/Amazon and AWS creates a "project": an AWS account in an organization managed by AWS, with AWS-managed guardrails (policies). Tested on such an account:
DenyAnyoneOutsideMyOrgAndAWS) deniessts:*to principals outside the project's organization, so Bref Cloud cannot assume its role. The only way out on the AWS side is to "activate advanced features", which cannot be undone.eu-north-1in Europe). Deploying the examples of the docs (us-east-1) fails with... with an explicit deny in a service control policy, which says nothing about the region.aws login, in a named profile: withoutAWS_PROFILE,serverless deployfails withAWS provider credentials not found. With it, osls reads these credentials fine.With the right region and profile, everything else worked (HTTP, CloudFront + assets, S3 private and public files, SQS worker,
bref:cli).The docs now recommend against projects, for Bref Cloud and Serverless CLI users alike, in a new "AWS projects" section of the setup page (the Bref Cloud UI will link to
/docs/setup#aws-projects). The main argument is not Bref Cloud: projects don't fit how companies run production on AWS (their own AWS Organization and policies, per-team permissions, cross-account integrations for monitoring/security/deployment tools, OIDC for CI/CD, any region), and AWS's own comparison says the same. For those who already have a project, the section explains what to change to deploy with the Serverless CLI, with the error messages so that the docs search finds them.Laravel guides
Unrelated to AWS, two install steps were missing and broke the recommended setup:
serverless.ymlenabledserverless-lift, but the getting started never installed it: the very first deploy failed. Comment out the Lift plugin in the serverless.yml stub laravel-bridge#212 comments the plugin out (like the constructs), and the guides that use constructs (queues, file storage, website assets) now tell to uncomment it. They also usedserverless plugin install, which does not exist for Bref Cloud users (they don't install osls globally), so they now usenpm install --save-dev serverless-lift.s3disk requiresleague/flysystem-aws-s3-v3, which was never mentioned: anyStorage::call failed withClass "League\Flysystem\AwsS3V3\PortableVisibilityConverter" not found, including in queued jobs.Also documented:
QUEUE_FAILED_DRIVER: 'null'for applications without a database (otherwise storing a failed job fails too), and the Free plan closing AWS accounts after 6 months unless upgraded.To release together with brefphp/laravel-bridge#212: with the current stub (plugin enabled), the getting started no longer installs Lift.