// Path relative to the copy in the `website/` folder
# Setup
You can deploy PHP applications with Bref using either:
- [Bref Cloud](https://bref.sh/cloud) (simplest, most features, free trial)
- or the [Serverless CLI](https://github.com/oss-serverless/osls) (more complex, fewer features built-in, free)
Bref Cloud is the easiest way to deploy PHP applications. It simplifies setting up and managing AWS credentials, and it provides a dashboard to manage your applications, view logs, and more. Learn more about [Bref Cloud](https://bref.sh/cloud).
This page will help you set up your environment for either option.
Before getting started, you will need PHP (8.2 or greater) and [NPM](https://nodejs.org/) installed.
## Bref Cloud
To use Bref Cloud, you will need a [Bref Cloud](https://bref.sh/cloud) account, an AWS account, and the `bref` CLI. Let's get started:
### Bref Cloud account
First, visit [bref.cloud](https://bref.cloud) to create an account.
### AWS account
Bref Cloud deploys your applications to your AWS account.
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](https://bref.sh/docs/setup/cloud-security).
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
Next, let's install the Bref CLI:
```shell
composer global require bref/cli
```
Finally, let's connect the CLI to your Bref Cloud account:
```shell
bref login
```
If the `bref` command is not found, or if you want more details on how to install the CLI, read the detailed [installation instructions](https://bref.sh/docs/setup/cloud-getting-started).
That's it, you're ready to use Bref with Bref Cloud!
} title="Get started with Laravel" arrow="true" href="https://bref.sh/docs/laravel/getting-started" />
} title="Get started with Symfony" arrow="true" href="https://bref.sh/docs/symfony/getting-started" />
## Serverless CLI
If you don't want to use Bref Cloud, you can deploy PHP applications using the open-source [Serverless CLI](https://github.com/oss-serverless/osls).
To use Bref with the Serverless CLI, you will need an AWS account, the `serverless` CLI, and AWS credentials. Let's get started:
### AWS account
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).
> [!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
Bref relies on the [Serverless Framework](https://github.com/oss-serverless/osls) and AWS access keys to deploy applications. You will need to install the `serverless` CLI using NPM:
```bash
npm install -g osls
```
> [!NOTE]
>
> The original [Serverless Framework](https://serverless.com/) is no longer open-source. An open-source alternative is [OSS Serverless](https://github.com/oss-serverless/osls), created and maintained by Bref maintainers. This is a drop-in replacement for the original CLI and is used throughout this documentation.
### AWS credentials
Finally, we need AWS credentials so that the `serverless` CLI can deploy to AWS.
> [!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](https://bref.sh/docs/setup/setup/aws-keys)
- Set up those keys by running:
```bash
serverless config credentials --provider aws --key "key" --secret "secret"
```
This will store the credentials in `~/.aws/credentials` (the [official file for AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)). This is the same as running the `aws configure` command with the `aws` CLI.
Alternatively (for example in CI/CD), you can store credentials in environment variables:
```bash
export AWS_ACCESS_KEY_ID=key
export AWS_SECRET_ACCESS_KEY=secret
```
That's it, you're ready to use Bref with the Serverless CLI!
} title="Get started with Laravel" arrow="true" href="https://bref.sh/docs/laravel/getting-started" />
} title="Get started with Symfony" arrow="true" href="https://bref.sh/docs/symfony/getting-started" />
> [!NOTE]
>
> 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](https://bref.sh/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.