Development Docker Image

After the container starts, you should be able to access the installation in a browser, e.g. http://localhost:8080. It can take a few minutes for the container to configure itself after the first launch. If the page doesn't open, try refreshing it until it loads.

Using the Image

After creating the container, you can control it on the Containers / Apps tab in Docker Desktop. Please note that deleting the container will also delete any data and files that you created in the container. You can map Docker volumes to preserve your data — see the example below.

Running with Data Persistence

You can run the container from the command line with volume mounts to protect your files and database:

docker run -d \ --name my-october \ -p 8080:80 \ -p 3306:3306 \ -v my_october_files:/var/www/html \ -v my_october_db:/var/lib/october-mysql \ octobercms/october:latest

With this configuration, you can delete and recreate the container without losing your data.

Editing files in the container

You can now edit theme files and experiment with creating plugins.

Running CLI commands in the container

The Remote-Containers: Attach to Running Container command described above connects the Visual Studio Code Terminal to the container shell. To open the Terminal, use the ctrl+` hotkey or select View / Terminal from the main menu. The Terminal opens in the October CMS installation directory, which is /var/www/html.

In the Terminal you can run any CLI commands, including Artisan and Composer commands. Run php artisan to see the list of available commands.

Accessing the database

The MariaDB database is called octobercms. You can access it using the mysql CLI tool from the Visual Studio Code Terminal or your host machine.

• In the Visual Studio Code Terminal run mysql -uroot -proot octobercms.
• Alternatively, if you forwarded the database port during the container creation and you have the MySQL client tools installed on your host computer, you can connect from your host machine in Windows Command Prompt: mysql --host=127.0.0.1 -uroot -proot --port=3307 octobercms. The port argument is the port number you entered in the container configuration.
• Alternatively, if you configured the database port forwarding, you can use any database GUI tool, for example, MySQL Workbench.

After the container starts, you should be able to access the installation in a browser, e.g. http://localhost:8080. It can take a few minutes for the container to configure itself after the first launch. If the page doesn't open, try refreshing it until it loads.

Using the Image

After creating the container, you can control it on the Containers / Apps tab in Docker Desktop. Please note that deleting the container will also delete any data and files that you created in the container. You can map Docker volumes to preserve your data — see the example below.

Running with Data Persistence

You can run the container from the command line with volume mounts to protect your files and database:

docker run -d \ --name my-october \ -p 8080:80 \ -p 3306:3306 \ -v my_october_files:/var/www/html \ -v my_october_db:/var/lib/october-mysql \ octobercms/october:latest

With this configuration, you can delete and recreate the container without losing your data.

Editing files in the container

You can now edit theme files and experiment with creating plugins.

Running CLI commands in the container

The Remote-Containers: Attach to Running Container command described above connects the Visual Studio Code Terminal to the container shell. To open the Terminal, use the ctrl+` hotkey or select View / Terminal from the main menu. The Terminal opens in the October CMS installation directory, which is /var/www/html.

In the Terminal you can run any CLI commands, including Artisan and Composer commands. Run php artisan to see the list of available commands.

Accessing the database

The MariaDB database is called octobercms. You can access it using the mysql CLI tool from the Visual Studio Code Terminal or your host machine.

• In the Visual Studio Code Terminal run mysql -uroot -proot octobercms.
• Alternatively, if you forwarded the database port during the container creation and you have the MySQL client tools installed on your host computer, you can connect from your host machine in Terminal: mysql --host=127.0.0.1 -uroot -proot --port=3307 octobercms. The port argument is the port number you entered in the container configuration.
• Alternatively, if you configured the database port forwarding, you can use any database GUI tool, for example, MySQL Workbench.

Prerequisites

• Install Docker Desktop for Windows.
• Install WSL 2 (Windows Subsystem for Linux). Open Windows Command Prompt or PowerShell and run wsl --install. If WSL is already installed, install a Linux distribution from the Microsoft Store — we recommend Ubuntu 24.04. Git is included.
• Enable Docker's WSL integration for your distribution. In Docker Desktop, go to Settings → Resources → WSL Integration and enable integration for your distribution (e.g. Ubuntu-24.04). This allows the docker command to work inside the WSL terminal.

Setup

• Start Ubuntu from the Windows Start menu.
• Clone the October CMS Docker toolkit and enter the directory:

git clone https://github.com/octobercms/docker.git cd docker

• Run the setup wizard: ./october-setup myapp

  The wizard will ask you to configure the environment (development or production), port numbers, and optional services. For your first site, the defaults work well.

• Start the site: ./launcher start myapp
• Access the site at http://localhost (or the port you chose during setup). The first start may take a few minutes while the container installs October CMS.

Using the Development Environment

Common commands

The launcher script provides a set of commands for managing your site:

• ./launcher start myapp — Start the site containers.
• ./launcher stop myapp — Stop the site containers.
• ./launcher restart myapp — Restart the site containers.
• ./launcher enter myapp — Open a shell inside the web container.
• ./launcher logs myapp — View container logs.
• ./launcher status — Show all sites and their status.

Editing files

Open VS Code attached directly to the running container:

./launcher code myapp

This opens Visual Studio Code with the Dev Containers extension connected to the web container, giving you full IDE support with IntelliSense, integrated debugging with Xdebug, and terminal access inside the container.

Accessing files from Windows

Site files live inside WSL 2 for optimal Docker performance. To access them with Windows tools like Tortoise Git or Windows Explorer, the launcher can mount the sites directory as a Windows drive via Samba:

./launcher mount

Your sites will be available at a drive letter (e.g. Z:\myapp). To disconnect, run ./launcher unmount. The WSL IP changes on reboot, so you'll need to run ./launcher mount each time you restart your machine.

Running CLI commands

Open a shell inside the container to run Artisan and Composer commands:

./launcher enter myapp php artisan

Multiple sites

You can run multiple October CMS sites from one installation. Each site has isolated containers and data:

./october-setup blog ./october-setup shop --port 8080 ./launcher start blog ./launcher start shop

Rebuilding a site

If something goes wrong, you can destroy and recreate the containers without losing your application files and database:

./launcher destroy myapp ./launcher start myapp

Prerequisites

• Install Docker Desktop for macOS or Linux.

Setup

• Open Terminal.
• Clone the October CMS Docker toolkit and enter the directory:

git clone https://github.com/octobercms/docker.git cd docker

• Run the setup wizard: ./october-setup myapp

  The wizard will ask you to configure the environment (development or production), port numbers, and optional services. For your first site, the defaults work well.

• Start the site: ./launcher start myapp
• Access the site at http://localhost (or the port you chose during setup). The first start may take a few minutes while the container installs October CMS.

Using the Development Environment

Common commands

The launcher script provides a set of commands for managing your site:

• ./launcher start myapp — Start the site containers.
• ./launcher stop myapp — Stop the site containers.
• ./launcher restart myapp — Restart the site containers.
• ./launcher enter myapp — Open a shell inside the web container.
• ./launcher logs myapp — View container logs.
• ./launcher status — Show all sites and their status.

Editing files

Open VS Code attached directly to the running container:

./launcher code myapp

This opens Visual Studio Code with the Dev Containers extension connected to the web container, giving you full IDE support with IntelliSense, integrated debugging with Xdebug, and terminal access inside the container.

Running CLI commands

Open a shell inside the container to run Artisan and Composer commands:

./launcher enter myapp php artisan

Multiple sites

You can run multiple October CMS sites from one installation. Each site has isolated containers and data:

./october-setup blog ./october-setup shop --port 8080 ./launcher start blog ./launcher start shop

Rebuilding a site

If something goes wrong, you can destroy and recreate the containers without losing your application files and database:

./launcher destroy myapp ./launcher start myapp