# Get started

This guide provides instructions for deploying and working with Laravel on Upsun.

## Before you begin

You need:

- [Git](https://git-scm.com/downloads).
  Git is the primary tool to manage everything your app needs to run.
  Push commits to deploy changes and control configuration through YAML files.
  These files describe your infrastructure, making it transparent and version-controlled.
- A Upsun account.
  If you don't already have one, [register for a trial account](https://auth.upsun.com/register).
  You can sign up with an email address or an existing GitHub, Bitbucket, or Google account.
  If you choose one of these accounts, you can set a password for your Upsun account later.
- The [Upsun CLI](https://docs.upsun.com/administration/cli.md).
  This lets you interact with your project from the command line.
  You can also do most things through the [Web Console](https://docs.upsun.com/administration/web.md).

## 1. Create your Laravel app

1. To create a new Laravel project, run the following commands:

   ```bash  {location="Terminal"}
   composer create-project laravel/laravel:^11.0 <PROJECT_NAME>
   cd <PROJECT_NAME>
   git init .
   ```

   Alternatively, you can deploy an **existing Laravel project**. To do so, `cd` into your Laravel repository root folder.

2. To generate a sensible default Upsun configuration,
   run the following command from within the project's directory:

   ```bash  {location="Terminal"}
   upsun project:init
   ```

   The Upsun CLI detects a PHP & Laravel stack.
   Follow the prompts to specify a name for your project and select the needed services.
   While optional, it is recommended to add [Redis](https://docs.upsun.com/add-services/redis.md) to your project to handle Laravel cache, queues & sessions.

   The `.upsun/config.yaml` and `.environment` configuration files are generated.

3. Enable the PHP extensions required by the services you selected. 
   For example, `pdo_mysql` is enabled by default, but you may need to enable others like `redis` or `pdo_pgsql`:

   ```yaml  {location=".upsun/config.yaml"}
   applications:
     myapp:
       [...]
       runtime:
         extensions:
           - redis
           - pdo_pgsql
   ```
   See all the [available PHP extensions](https://docs.upsun.com/languages/php/extensions.md).

3. Laravel requires an [encryption key](https://laravel.com/docs/master/encryption#gracefully-rotating-encryption-keys). 
   To generate the key locally, run `php artisan key:generate`.
   Copy the key from your local `.env` file into `.environment` as follows:

   ```bash  {location=".environment"}
   export APP_KEY="base64:<APP_KEY>"
   ```

4. Add and commit your changes:

   ```bash  {location="Terminal"}
   git add .upsun/config.yaml .environment
   git commit -m "Add Upsun configuration"
   ```

## 2. Create your Upsun project

To create a project on Upsun, run the following command from within the project's directory:

```bash  {location="Terminal"}
upsun project:create --title <PROJECT_TITLE> --set-remote
```

The `--set-remote` flag sets the new project as the remote for this repository.

**Tip**: 

You can link any repository to an existing Upsun project using the following command:

    Terminal

```bash {}
upsun project:set-remote <PROJECT_ID>
```

## 3. Deploy your project

To deploy your project, run the following command:

```bash  {location="Terminal"}
upsun push
```

During deployment, the logs from the Upsun API are displayed in your terminal so you can monitor progress.
To stop the display of the logs **without interrupting the deployment**,
use `CTRL+C` in your terminal.
To go back to displaying the logs, run `upsun activity:log`.

Congratulations, your first Laravel app has been deployed on Upsun!

**Tip**: 

Now that your app is deployed in production mode,
you can [set up a custom domain](https://docs.upsun.com/domains/steps.md).

## 4. Configure write access

The Upsun default configuration stipulates three writable folders in `.upsun/config.yaml`:

- `"/.config"`
- `"bootstrap/cache"`
- `"storage"`

If your application writes content outside of these default ones,
you can [set up mounts](https://docs.upsun.com/create-apps/image-properties/mounts.md).

## 5. Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash  {location="Terminal"}
   upsun branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch,
   and activates a related environment on Upsun.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.

   For example, edit the `resources/views/welcome.blade.php` template and make the following visual changes:

   ```html {location="resources/views/welcome.blade.php",}

   -    **Laravel**
   +    **Laravel On Upsun**

   ```

3. Add and commit your changes:

   ```bash  {location="Terminal"}
   add .
   git commit -a -m "Update title"
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash  {location="Terminal"}
   upsun deploy
   ```

   Note that each environment has its own domain name.
   To view the domain name of your new environment, run the following command:

   ```bash  {location="Terminal"}
   upsun url --primary
   ```

5. Iterate by changing the code, committing, and deploying.
   When satisfied with your changes, merge them to the main branch, deploy,
   and remove the feature branch:

   ```bash  {location="Terminal"}
   git checkout main
   git merge feat-a
   upsun environment:delete feat-a
   git branch -d feat-a
   upsun deploy
   ```

   Note that deploying to production is fast because the image built for the `feat-a` environment is reused.

   For a long running branch, keep the code up-to-date with the main branch by using `git merge main` or `git rebase main`.
   Also, keep the data in sync with the production environment by using `upsun env:sync`.

## 6. Optional: Use a third-party Git provider

When you choose to use a third-party Git hosting service,
the Upsun Git repository becomes a read-only mirror of the third-party repository.
All your changes take place in the third-party repository.

Add an integration to your existing third-party repository:

- [BitBucket](https://docs.upsun.com/integrations/source/bitbucket.md)
- [GitHub](https://docs.upsun.com/integrations/source/github.md)
- [GitLab](https://docs.upsun.com/integrations/source/gitlab.md)