We will rely on the terminal and the Upsun CLI to deploy our application. Our end-goal is to deploy our application with a real production domain at the end.
Let’s review the steps we will have to go through:
- Create a new Upsun project
- Generating the base Upsun configuration for our Laravel app
- Configuring our base connection to services
- Setting up our environment variables
- Do our first deploy
- Setting up Laravel Horizon to handle our queues
- Configuring our domain
Create a new Upsun project
Launch your terminal and make sure you have the Upsun CLI available. You can refer to this page on the documentation to install the CLI tool.
cd into your Laravel application base directory and start by logging in with upsun login. Go through the web-based authentication process.
Once done, we will create a new empty project with upsun project:create. Follow the prompts:
The CLI will auto-detect your git repository and will add the Upsun endpoint as a new remote for your repository:
The Upsun platform will now take a minute to provision your project:
Let’s move on to creating the configuration.
Generating the base Upsun configuration for our Laravel app
The Upsun CLI comes bundled with our nifty upsun ify command that will auto-generate a base configuration based on the runtime and framework you are using.
Let’s launch it in our Laravel directory:
upsun ify detects a Laravel app and automatically setup the configuration for PHP, composer and npm. We now need to tell Upsun which services we are running. Just select in the list the services the app relies on. In our case, we will elect PostgreSQL and Redis:
If your application needs to handle local files on the filesystem, it is recommended to add Network Storage as this will allow multiple instances of the application or a worker (horizon) to access the files as well.
You can now deploy your application to Upsun!
To do so, commit your files and deploy your application using the Upsun CLI:
The configuration is now generated. Let’s follow the directions and commit it:
Configuring the application to access the services
In order for our Laravel application to connect to our services, we need to inject the proper configuration.
First add the redis and pdo_pgsql extensions to .upsun/config.yaml if needed:
Add the change to the git index and commit:
We will now look at the .environment file that auto-generates some variables for our app. The upsun ify command should have added the necessary variable declarations for Laravel. This file maps default Upsun environment variables to the ones needed by Laravel. You can adjust this file if needed or add additional mappings like we have done here with the email settings:
Last step before deploying our app, we need to inject our remaining configuration through dynamic environment variables.
Setting dynamic environment variables
Open your local .env file. As Upsun already handle the specific services (database, cache, queues) settings, we only need to setup the global configuration. Here are the ones we need for our Wooply project. Note that we use the env: prefix to expose the variable to the container and the app directly.
The MODEL_CACHE_ENABLED and LPL_ variables that we added here are requirements for additional packages and not default for Laravel.
Variable can also be overriden per environment if you set their level to environment instead of project.
Everything is now ready to push our code.
If you are using private packages like Laravel Nova, you will need to inject the composer configuration as a variable. It can be done with the following:
First deploy
Still in the base directory, you can now use upsun push to push your commits to the Upsun remote:
The Upsun deployment pipeline will start building your project. We will go into this later in more details. If you encountered an error during that process, update the configuration or variables and do a upsun redeploy to restart the process.
The deploy phase is now complete and prints out your project URLs. Not that they are auto-generated for now as we don’t have added any domain yet:
Our project has also been deployed with default minimal resources for our containers and is now available on https://main-bvxea6i-snacckbxx5cee.us-3.platformsh.site/. Database migrations are run automatically on each deploy to ensure your code matches the database schema. You can see what exactly happens in the .upsun/config.yaml inside the build and deploy hooks.
Now that our application is working, let’s configure our Horizon worker.
Setting up Horizon workers and queues
If needed, add laravel/horizon to your local project and follow the documentation on the Horizon page.
We are now going to add a separate application on our project. Open .upsun/config.yaml and add the following:
This way, a new container will be started automatically and will spawn the Horizon process.
If you have restricted access to horizon in your HorizonServiceProvider.php, login to your application through the web. Once done, head to /horizon and you should be able to access your horizon dashboard:
Horizon will handle jobs that are populated by the queue. If you need to customize how Horizon works (queues, processes, …), please refer to the official Laravel Horizon documentation.
As any other container, the resources of the Horizon container can be customized. Head to the Configure resources panel of the Upsun console and change the resources as needed:
Adding our domain name to the project
On console.upsun.com , head to your main environment and click the top-right action: Go Live.
Copy the provided CNAME and head to your DNS provider management panel. I’m using CloudFlare here but any will do.
Add the CNAME record to your DNS zone:
Note: If your DNS provider does not allow CNAME on @ records, take a look at Upsun documentation on alternatives.
Once done, add the domain to your project:
The Upsun platform will add the configuration and automatically provision Let’s Encrypt certificates for all your routes:
Our Laravel application is now live on its own domain! Last modified on April 17, 2026
