Laravel

Laravel is a PHP web application framework with expressive, elegant syntax. This guide walks you through the minimal requirements to successfully deploy your app.

Overview

Deploying a Laravel application on Clever Cloud requires:

PHP application
A database add-on: (MySQL or PostgreSQL)
An FS Bucket for persistent storage.

The following sections explain how to set up each instance step by step:

Configure your Laravel Application

Create a PHP application

From the Clever Cloud Console, create a new PHP application and choose your deployment method: git, GitHub or FTP.

Add `DocumentRoot` variable

Add the following environment variable in the Console: CC_WEBROOT="/public".

Or set it with the Clever Cloud CLI:

clever env set CC_WEBROOT /public

Add your application key variable

Make sure config/app.php contains the following line:

  'key' => env('APP_KEY'),

Locally, run php artisan key:generate. It should output something like base64:tQbFzxwUfOfKKqNlbjXuduwaUFDQUy+NL8DBfgb3o3s=.

Copy this value and add an environment variable named APP_KEY, with this value.

Configure monolog to use syslog

Make sure config/logging.php contains the following line:

  'default' => env('LOG_CHANNEL', 'stack'),

In your environment variables, add the LOG_CHANNEL=syslog environment variable. This allows you to read your application logs directly from the console or the CLI tool.

Optional: configure the front-end build

If you need to build your frontend assets (eg. JavaScript or CSS files), you can either add it as a step in your composer file, or you can add a post build hook with the CC_PRE_RUN_HOOK environment variable.

For example: CC_PRE_RUN_HOOK="npm install && npm run prod".

This step is necessary if you are building your Laravel application with Blade, for example.

Connect a database

Edit config/database.php to set the correct environment variable names. For example, replace DB_xxx by MYSQL_ADDON_xxx for a MySQL database.

For instance for MySQL:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
   // ...
   'connections' => [
     // ...
        'mysql' => [
            'driver' => 'mysql',
            'host' => env('MYSQL_ADDON_HOST', '127.0.0.1'),
            'port' => env('MYSQL_ADDON_PORT', '3306'),
            'database' => env('MYSQL_ADDON_DB', 'forge'),
            'username' => env('MYSQL_ADDON_USER', 'forge'),
            'password' => env('MYSQL_ADDON_PASSWORD', ''),
            'unix_socket' => env('DB_SOCKET', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => null,
        ],
    // ...
    ]
  // ...

Create a database add-on (either MySQL or PostgresSQL) and link it to your application. If your add-on already exists, use the Service Dependencies > Link add-ons dropdown menu in your application options, to select the name of the add-on you want to link and use the add button to finish the process.

Optional: automatically run migrations upon deployment

If you want to have database migrations automatically run during each deployment, add this hook instruction to the application’s environment variables CC_POST_BUILD_HOOK=php artisan migrate --force

Configure storage

Create a FS Bucket add-on and link it to your application. Note its host (you can see it from the add-on configuration panel, or in the environment variables exported by the add-on). It looks like bucket-01234567-0123-0123-0123-012345678987-fsbucket.services.clever-cloud.com.

Create a new environment variable called CC_FS_BUCKET and set /storage/app:<bucket-host> as its value.

Optional Further Configuration

Task scheduling

If your app uses task scheduling, you need to configure a cron to run the scheduling process:

Create a clevercloud/cron.json file in your project, containing:

[
    "* * * * * $ROOT/clevercloud/cron.sh"
]

This installs a cron to run clevercloud/cron.sh every minute.

Create a clevercloud/cron.sh file in your project (with execute permissions), containing:

#!/bin/bash -l
set -euo pipefail

pushd "$APP_HOME"
php artisan schedule:run >> /dev/null 2>&1

Note: the PHP CLI process uses a memory_limit configuration value that depends on the instance’s size (you can verify this value by connecting to your app using SSH and running php -i).

If one of your scheduled tasks needs to allocate more memory than this limit, the php artisan schedule:run process is going to silently crash.

To allow it to use more memory, you can call ini_set() inside a php_sapi_name() === 'cli' condition from an early hook to the app’s lifecycle (like the AppServiceProvider).

See this Gist for an example implementation.

Trusted Proxy

To ensure Laravel correctly handles HTTP requests when using the Clever Cloud HTTP reverse proxy (Sōzu), add the following code to the config/trustedproxy.php file:

1
2
3
4
<?php
return [
    'proxies' => env('CC_REVERSE_PROXY_IPS'),
];

This environment variable exists in any Clever Cloud instance. This configuration specifies to trust Clever Cloud proxies, allowing Laravel to seamlessly recognize HTTP requests in the presence of a proxyhugo server.