Get started

​

1. Create your Laravel app

1. To create a new Laravel project, run the following commands:
   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:
   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 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:
   .upsun/config.yaml

   applications:
     myapp:
       [...]
       runtime:
         extensions:
           - redis
           - pdo_pgsql
   
   See all the available PHP extensions.
4. Laravel requires an encryption key.
   To generate the key locally, run php artisan key:generate. Copy the key from your local .env file into .environment as follows:
   .environment

   export APP_KEY="base64:<APP_KEY>"
   
5. Add and commit your changes:
   Terminal

   git add .upsun/config.yaml .environment
   git commit -m "Add Upsun configuration"
   

​

2. Create your Upsun project

upsun project:create --title <PROJECT_TITLE> --set-remote

upsun project:set-remote <PROJECT_ID>

​

3. Deploy your project

upsun push

​

4. Configure write access

• "/.config"
• "bootstrap/cache"
• "storage"

​

5. Make changes to your project

1. Create a new environment (a Git branch) to make changes without impacting production:
   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:
   <meta name="viewport" content="width=device-width, initial-scale=1">
   -    <title>Laravel</title>
   +    <title>Laravel On Upsun</title>
   {/* Fonts */}
   
3. Add and commit your changes:
   Terminal

   add .
   git commit -a -m "Update title"
   
4. Deploy your changes to the feat-a environment:
   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:
   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:
   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

• BitBucket
• GitHub
• GitLab