How to Install October CMS to an existing Laravel application

This is a guide to installing October CMS 3.x atop an existing Laravel 9 application. The major 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 there are slight differences in the class names.

Install Laravel 9 and then October Rain

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

composer create-project laravel/laravel mylaravel "^9.0"

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

cd mylaravel
composer require october/rain "^3.0"

Authenticate and Install October 3

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 "^3.0"

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;

Register and Publish October CMS Files

The following steps will register the core provider and copy the vendor files from October CMS.

Register October CMS Providers

In the file config/app.php, replace the use statement to replace the default aliases.

// Replace
use Illuminate\Support\Facades\Facade;

// With
use October\Rain\Support\Facade;

In the same file config/app.php, add the following to the providers key.

'providers' => [
    // ...

    // Boot October CMS
    System\ServiceProvider::class,
],

Publish Default October CMS Files

To publish the files, follow these steps:

  1. Open the October CMS public repo: https://github.com/octobercms/october
  2. Navigate to Code → Download ZIP
  3. Save the zip and open it locally

Copy the following config files and folders from the zip file.

Copy Files

  • config/system.php
  • config/backend.php
  • config/media.php
  • config/cms.php

Copy Folders

  • 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.

5 Likes

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

3 Likes