OctoberCMS¶

October is a free, open-source, self-hosted CMS platform based on the Laravel PHP Framework. It is especially known for its simplicity, flexibility and modern design.

Note

For this guide you should be familiar with the basic concepts of

License¶

The OctoberCMS platform is released under the MIT License. All relevant information can be found in the LICENSE file in the repository of the project. Please also review the Marketplace terms if you plan to use plugins or themes from the official Marketplace.

Prerequisites¶

We’re using PHP in the stable version 8.1:

[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.1'
[isabell@stardust ~]$

You need to know your MySQL database user and password:

You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
[isabell@stardust ~]$

Your domain needs to be set up:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

During the setup process you will be asked for database credentials. We use MySQL and suggest you use an additional database for October to save your data. You have to create this database first using the following command.

[isabell@stardust ~]$ mysql -e "CREATE DATABASE ${USER}_october"
[isabell@stardust ~]$

We will install October using composer. First, make sure that your DocumentRoot is empty:

[isabell@stardust ~]$ rm html/nocontent.html
[isabell@stardust ~]$

Initialize the composer project in your DocumentRoot:

[isabell@stardust ~]$ composer create-project october/october /var/www/virtual/$USER/html
[...]
[isabell@stardust ~]$

Change to your DocumentRoot and then start the installer:

[isabell@stardust ~]$ cd /var/www/virtual/$USER/html
[isabell@stardust html]$ php artisan october:install

The CLI installer/setup will now ask you for various settings:

Application URL: the domain of your uberspace e.g. https://isabell.uber.space

Backend URI: how you will access your backend, e.g. /backend

Database type: MySQL (default)

MySQL host: localhost (default)

MySQL port: 3306 (default)

Database name: isabell_october (the name of the database you created earlier)

MySQL login: isabell (your username)

MySQL password: your MySQL password that you’ve got from my_print_defaults client

Include demo content, yes or no?

License Key

Next, you will be asked to run artisan to migrate the database:

[isabell@stardust html]$ php artisan october:migrate

To finish installation, append the backend URI you set up earlier (e.g. https://isabell.uber.space/backend). Here, you will be asked to set up the admin user.

Best practices¶

You can use the October CLI which we used to setup your instance also to e.g. install plugins. See the Console command list to explore all possibilities.

Updates¶

Note

Check the update feed regularly to stay informed about the newest version. You will also be notified in the October backend if Updates are available.

To update October and your installed plugins you can use the october:update CLI command in the root directory of the application. This will update the core application and plugin files, followed by a database migration.

[isabell@stardust ~]$ cd ~/html
[isabell@stardust html]$ php artisan october:update
Updating October...
Found 1 new update!
Downloading application files
[...]
[isabell@stardust ~]$

Tested with OctoberCMS 3.1.25, Uberspace 7.13, PHP 8.1

Written by: Daniel Kratz <https://danielkratz.com>