How to Install October CMS to an existing Laravel application

A guide to installing October CMS 3 atop an existing Laravel 9 application. The significant steps involve replacing Laravel’s Illuminate package with October’s Rain package, which represents an extended technology version of Laravel and adds the necessary core features to run October CMS.

Be sure to follow this guide carefully, as slight differences exist in class names.

Install Laravel 9 and then October Rain

To get started, assume we have a brand new Laravel installation with the following command:

composer create-project laravel/laravel mylaravel

In the newly created directory, require the October CMS Rain library.

cd mylaravel
composer require october/rain

Authenticate and Install October CMS

Authenticate with the October CMS gateway by setting your project key.

php artisan project:set <license key>

Require all the October CMS modules.

composer require october/all

When prompted to trust composer/installers enter “y” for yes.

Do you trust "composer/installers" to execute code and wish to enable it now?

Replace Illuminate references with Rain Library

The following steps are used to replace Illuminate with Rain.

Update Application Container

In the file bootstrap/app.php the Illuminate\Foundation\Application class should be replaced with October\Rain\Foundation\Application.

// File bootstrap/app.php

// Replace
$app = new Illuminate\Foundation\Application(
    $_ENV['APP_BASE_PATH'] ?? dirname(__DIR__)

// With
$app = new October\Rain\Foundation\Application(
    $_ENV['APP_BASE_PATH'] ?? dirname(__DIR__)

Update HTTP Kernel

In the file app/Http/Kernel.php the App\Http\Kernel class should extend October\Rain\Foundation\Http\Kernel.

// File app/Http/Kernel.php

// Replace
use Illuminate\Foundation\Http\Kernel as HttpKernel;

// With
use October\Rain\Foundation\Http\Kernel as HttpKernel;

Update Console Kernel

In the file app/Console/Kernel.php the App\Console\Kernel class should extend October\Rain\Foundation\Console\Kernel.

// File app/Console/Kernel.php

// Replace
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

// With
use October\Rain\Foundation\Console\Kernel as ConsoleKernel;

Update Exception Handler

In the file app/Exceptions/Handler.php the App\Exceptions\Handler class should extend October\Rain\Foundation\Exception\Handler.

// File app/Exceptions/Handler.php

// Replace
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;

// With
use October\Rain\Foundation\Exception\Handler as ExceptionHandler;

Publish October CMS Files

The following steps will copy the vendor files from October CMS. To publish the files, follow these steps:

  1. Open the October CMS public repo: GitHub - octobercms/october: Self-hosted CMS platform based on the Laravel PHP Framework.
  2. Navigate to Code → Download ZIP
  3. Save the zip and open it locally

Copy the following folders from the zip file.

  • config/
  • plugins/
  • themes/

Final Steps

Assuming that your database is configured and running, run the October CMS migration.

php artisan october:migrate

Next, to make CMS pages available to the frontend, remove or comment out the default route in the file routes/web.php.

Now you can open the /backend route to set up the administrator account.

Extra Steps

Some optional steps to configure your system:

  • If you plan on using the default Laravel path for views, uncomment this in the config/view.php file.

I never thought that you can actually do that. That is insane :exploding_head:


Thank you. I followed all the steps, but I already have my Laravel 9 project and changed default files. I end up having OctoberCMS on the root opening, so my didn’t seem to respond. I could not go to /backend and my views didn’t respond anymore. Surely it has to do with replacing Laravel’s Illuminate package with October’s Rain package. I use a VM and took a snapshot, so I just rollback. Its just that I didn’t know the impact and somehow it doesn’t function either.

Great work! This will surely allow more users to get to OctoberCMS in the future.

You should add this to the “Getting started” section as well…

1 Like

Thanks for the tutorial. Works perfect!

Missing step in the end to have themes and modules assets working on frontend:

php artisan october:mirror
1 Like