Installing October CMS with Laravel Sail

Tutorial

Published on Feb 4, 2023 · Updated on Nov 8, 2026

# Installing October CMS with Laravel Sail

[Laravel Sail](https://laravel.com/docs/12.x/sail) is a light-weight command-line interface for Laravel's default Docker development environment. Since October CMS is built on Laravel, Sail can be added to an October CMS project to run PHP and MySQL in Docker containers. This article creates a new project, adds Sail to it, and installs October CMS inside the containers.

## Before You Begin

Install [Docker](https://www.docker.com/get-started/) and make sure it is running. Sail is supported on macOS, Linux and Windows through [WSL2](https://learn.microsoft.com/en-us/windows/wsl/about). On Windows, run the commands in this article from a WSL2 terminal.

The first two steps, creating the project and adding Sail to it, use PHP and [Composer](https://getcomposer.org/) on your computer. If they aren't installed, you can run those steps with Docker instead, as described in [Without PHP on Your Computer](#without-php-on-your-computer). After that, PHP, Composer and MySQL run inside the containers.

Sail publishes the website on port 80 and MySQL on port 3306, so make sure no other web server or database is running on your computer before you start the containers.

## Create the Project

Create a new project in a directory called *myoctober* and enter it.

```bash
composer create-project october/october myoctober
cd myoctober
```

Composer copies the `.env.example` file to `.env` and generates the application key.

## Add Sail to the Project

Add Sail as a development dependency.

```bash
composer require laravel/sail --dev
```

October CMS runs Laravel's package discovery whenever Composer updates the project, so the Sail commands are available to Artisan as soon as the package is installed. Run the `sail:install` command to set up the containers.

```bash
php artisan sail:install --with=mysql --php=8.4
```

The `--with` option lists the services to include, and the `--php` option sets the PHP version of the application container. The command publishes a `compose.yaml` file to the project root and changes the database settings in the `.env` file to connect to the MySQL container:

```ini
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=database
DB_USERNAME=sail
DB_PASSWORD=password
```

The MySQL container creates the database named by `DB_DATABASE` the first time it starts, along with a dedicated `testing` database, and the command also points the project's `phpunit.xml` file at the `testing` database. To use a different database name, change `DB_DATABASE` now, before the containers start for the first time.

When Docker is running, `sail:install` also downloads the service images and builds the application image. This can take several minutes the first time.

> **Tip**: To preview outgoing email, include Mailpit with `--with=mysql,mailpit`. Sail then sets `MAIL_MAILER=smtp` and `MAIL_HOST=mailpit` in the `.env` file, and the captured messages are shown at `http://localhost:8025`. You can also add services later with `php artisan sail:add`.

## Without PHP on Your Computer

If PHP and Composer aren't installed on your computer, run the commands from the previous two steps in a temporary container using Sail's PHP and Composer image. The `docker run` prefix mounts the current directory into the container and runs the command as your user.

```bash
docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest composer create-project october/october myoctober
cd myoctober
docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest composer require laravel/sail --dev
docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest php artisan sail:install --with=mysql --php=8.4
```

Docker isn't available inside this container, so `sail:install` skips downloading and building the images, and the first `sail up` in the next step builds them instead.

## Start the Containers

Start the containers in the background.

```bash
./vendor/bin/sail up -d
```

The application container serves the website with the PHP development server (`php artisan serve`), which October CMS supports out of the box, so there is no web server to configure.

> **Tip**: Instead of typing `./vendor/bin/sail` each time, you can configure a shell alias with `alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'` and add it to your shell configuration file, such as `~/.bashrc` or `~/.zshrc`.

## Install October CMS

Run the installation command inside the application container.

```bash
./vendor/bin/sail artisan october:install --no-interaction
```

Since `sail:install` already wrote the database connection to the `.env` file, the installer can skip its questions. In non-interactive mode it migrates the database, migrates Tailor and seeds the demo theme.

From now on, run Artisan and Composer commands through Sail, such as `./vendor/bin/sail artisan` and `./vendor/bin/sail composer`. The `mysql` host name only resolves inside the containers, so `php artisan` on your computer cannot reach the database.

> **Tip**: The non-interactive install doesn't ask for a license key, so you can explore October CMS locally straight away. To unlock updates and marketplace access, add your [License Key](https://octobercms.com/help/site/projects#project-id) with `./vendor/bin/sail artisan project:set <license key>`.

If you prefer the interactive installer, run `./vendor/bin/sail artisan october:install` without the option instead. It asks for the language, application URL, backend URI, database connection, demo theme and License Key, offering the values from the `.env` file as defaults, and then installs the October CMS packages with Composer. Afterwards, initialize the database with `./vendor/bin/sail artisan october:migrate`.

## Open the Website

Open the website in a browser.

```
http://localhost
```

Add `/admin` to the URL to access the admin panel and create your first administrator account.

```
http://localhost/admin
```

> **Tip**: If port 80 is taken on your computer, set another port with `APP_PORT=8080` in the `.env` file, update `APP_URL` to `http://localhost:8080` to match, and run `./vendor/bin/sail up -d` again. The `FORWARD_DB_PORT` variable does the same for the MySQL port.

## Working with Sail

Stop the containers when you are done, and start them again with `up -d`.

```bash
./vendor/bin/sail stop
./vendor/bin/sail up -d
```

Commands for the project run inside the application container.

```bash
./vendor/bin/sail artisan plugin:list
./vendor/bin/sail composer install
./vendor/bin/sail shell
```

To connect to the MySQL database from a database client on your computer, use `localhost` port 3306 with the `DB_USERNAME` and `DB_PASSWORD` values from the `.env` file. The `root` user also uses the `DB_PASSWORD` value as its password.

## See Also

- [Installation](https://docs.octobercms.com/4.x/setup/installation.html)
- [Production Configuration](https://docs.octobercms.com/4.x/setup/configuration.html#production-configuration)
- [Laravel Sail Documentation](https://laravel.com/docs/12.x/sail)
- [Installing October CMS with DDEV](https://octobercms.com/support/article/installing-october-cms-with-ddev)
- [Installing October CMS with Laragon](https://octobercms.com/support/article/installing-october-cms-with-laragon)
- [Deploying October CMS with the Deploy Plugin](https://octobercms.com/support/article/deploying-october-cms-with-the-deploy-plugin)

On this page

Before You Begin
Create the Project
Add Sail to the Project
Without PHP on Your Computer
Start the Containers
Install October CMS
Open the Website
Working with Sail
See Also

Laravel Sail is a light-weight command-line interface for Laravel's default Docker development environment. Since October CMS is built on Laravel, Sail can be added to an October CMS project to run PHP and MySQL in Docker containers. This article creates a new project, adds Sail to it, and installs October CMS inside the containers.

Before You Begin

Install Docker and make sure it is running. Sail is supported on macOS, Linux and Windows through WSL2. On Windows, run the commands in this article from a WSL2 terminal.

The first two steps, creating the project and adding Sail to it, use PHP and Composer on your computer. If they aren't installed, you can run those steps with Docker instead, as described in Without PHP on Your Computer. After that, PHP, Composer and MySQL run inside the containers.

Sail publishes the website on port 80 and MySQL on port 3306, so make sure no other web server or database is running on your computer before you start the containers.

Create the Project

Create a new project in a directory called myoctober and enter it.

composer create-project october/october myoctober
cd myoctober

Composer copies the .env.example file to .env and generates the application key.

Add Sail to the Project

Add Sail as a development dependency.

composer require laravel/sail --dev

October CMS runs Laravel's package discovery whenever Composer updates the project, so the Sail commands are available to Artisan as soon as the package is installed. Run the sail:install command to set up the containers.

php artisan sail:install --with=mysql --php=8.4

The --with option lists the services to include, and the --php option sets the PHP version of the application container. The command publishes a compose.yaml file to the project root and changes the database settings in the .env file to connect to the MySQL container:

DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=database
DB_USERNAME=sail
DB_PASSWORD=password

The MySQL container creates the database named by DB_DATABASE the first time it starts, along with a dedicated testing database, and the command also points the project's phpunit.xml file at the testing database. To use a different database name, change DB_DATABASE now, before the containers start for the first time.

When Docker is running, sail:install also downloads the service images and builds the application image. This can take several minutes the first time.

Tip: To preview outgoing email, include Mailpit with --with=mysql,mailpit. Sail then sets MAIL_MAILER=smtp and MAIL_HOST=mailpit in the .env file, and the captured messages are shown at http://localhost:8025. You can also add services later with php artisan sail:add.

Without PHP on Your Computer

If PHP and Composer aren't installed on your computer, run the commands from the previous two steps in a temporary container using Sail's PHP and Composer image. The docker run prefix mounts the current directory into the container and runs the command as your user.

docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest composer create-project october/october myoctober
cd myoctober
docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest composer require laravel/sail --dev
docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/var/www/html" -w /var/www/html laravelsail/php84-composer:latest php artisan sail:install --with=mysql --php=8.4

Docker isn't available inside this container, so sail:install skips downloading and building the images, and the first sail up in the next step builds them instead.

Start the Containers

Start the containers in the background.

./vendor/bin/sail up -d

The application container serves the website with the PHP development server (php artisan serve), which October CMS supports out of the box, so there is no web server to configure.

Tip: Instead of typing ./vendor/bin/sail each time, you can configure a shell alias with alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)' and add it to your shell configuration file, such as ~/.bashrc or ~/.zshrc.

Install October CMS

Run the installation command inside the application container.

./vendor/bin/sail artisan october:install --no-interaction

Since sail:install already wrote the database connection to the .env file, the installer can skip its questions. In non-interactive mode it migrates the database, migrates Tailor and seeds the demo theme.

From now on, run Artisan and Composer commands through Sail, such as ./vendor/bin/sail artisan and ./vendor/bin/sail composer. The mysql host name only resolves inside the containers, so php artisan on your computer cannot reach the database.

Tip: The non-interactive install doesn't ask for a license key, so you can explore October CMS locally straight away. To unlock updates and marketplace access, add your License Key with ./vendor/bin/sail artisan project:set <license key>.

If you prefer the interactive installer, run ./vendor/bin/sail artisan october:install without the option instead. It asks for the language, application URL, backend URI, database connection, demo theme and License Key, offering the values from the .env file as defaults, and then installs the October CMS packages with Composer. Afterwards, initialize the database with ./vendor/bin/sail artisan october:migrate.

Open the Website

Open the website in a browser.

http://localhost

Add /admin to the URL to access the admin panel and create your first administrator account.

http://localhost/admin

Tip: If port 80 is taken on your computer, set another port with APP_PORT=8080 in the .env file, update APP_URL to http://localhost:8080 to match, and run ./vendor/bin/sail up -d again. The FORWARD_DB_PORT variable does the same for the MySQL port.

Working with Sail

Stop the containers when you are done, and start them again with up -d.

./vendor/bin/sail stop
./vendor/bin/sail up -d

Commands for the project run inside the application container.

./vendor/bin/sail artisan plugin:list
./vendor/bin/sail composer install
./vendor/bin/sail shell

To connect to the MySQL database from a database client on your computer, use localhost port 3306 with the DB_USERNAME and DB_PASSWORD values from the .env file. The root user also uses the DB_PASSWORD value as its password.