Development Docker Image
Start building your website or application today. It’s free.
The October CMS Development Docker Image includes everything you need to explore the platform and start building a website instantly, without purchasing a license and configuring your development machine. You can have a running October CMS container on your computer in a few minutes after reading this page or watching the video tutorial.
What's in the October CMS Development Docker Image?
The Image is based on the official PHP Docker Image and includes PHP 8, MySQL and Apache. The Image can be used for platform evaluation purposes and can be licensed and converted to a fully functional development environment. You can create multiple containers to work on different projects.
macOS, Windows, and Linux
The Image is compatible with ARM64 and AMD64 CPU architectures and can work on Windows, Linux and macOS systems with Intel and Apple M1 processors.
To protect your database and files, the Image allows you to store the platform source code and database on the host machine. You won’t lose your work if you accidentally delete the container. Just recreate the container and continue from where you left off!
Limitations
Although the Image includes a fully functional copy of October CMS, there are several limitations and the Image is not optimized for production environments. The following limitations can be removed by licensing the installation: 1) the platform PHP files are encrypted and not updatable - composer update and composer install can’t be used, 2) the installation adds a HTTP header to all responses: October-CMS-Dev: Unlicensed copy, for evaluation purposes only.
Installing and Using October CMS Development Docker Image
Please select your platform:
-
I’m using Windows
-
I’m using macOS or Linux
Select your preferred installation method:
-
Docker Desktop - the simplest but the most limited option
With this option you can launch a container in seconds but it doesn’t provide the filesystem and data persistence.
-
Interactive bash script - use the command line interface to configure the container
This option provides the filesystem and data persistence and makes several assumptions about your preferences to simplify the process.
-
Manual installation - the most flexible and fully configurable option
Create the container manually and configure the data and/or filesystem persistence as you need.
Installing the Image on Windows using Docker Desktop
This installation method doesn't provide data protection if the container is accidentally deleted. We don't recommend it if you are planning to convert the installation to a fully functional development environment for a client's project.
- Install and launch Docker Desktop for Windows.
-
Launch Command Prompt and run
docker pull octobercms/october-dev:latest - In Docker Desktop, go to Images, find the pulled image, and click Run.
- In the container configuration popup, click Optional Settings.
- Enter the container name, e.g. my-octobercms-test. If you skip that step, a container name will be generated automatically.
- Click the Plus icon in the Ports section to reveal settings for the port 80.
- Enter a forwarding port number for the container's port 80. You will use this port to access the installation in a browser. You can use 8080 or a similar value. Remember that you can't have two running containers that use the same port number. We recommend using a unique port number for every container.
- Optionally, enter a forwarding port number for the MySQL port 3306. You can use that port to connect to the MySQL server running in the container.
- Click Run to start the container.
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. This limitation doesn't exist in other installation methods.
Editing files in the container
You can access files in the container using the Remote-Containers extension for Microsoft Visual Studio Code.
- Install the extension.
- Open the Command Palette (
ctrl+shift+p) and select Remote-Containers: Attach to Running Container. - Select your container.
- That will open a new Code window. Click the Open Folder button in the sidebar and select the
/var/www/htmldirectory.
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 commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
Git is pre-installed in the Image, and you can clone and push code from inside the container. The user.name and user.email git configuration parameters are automatically copied into the container by the Visual Studio Code extension. To use SSH keys, you may need to configure the SSH agent on the host computer. Read the Remote-Containers extension documentation to learn how to configure SSH. With other installation methods, you can pull and push files from your host machine as you usually do.
Accessing the MySQL database
The MySQL 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 MySQL 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. Theportargument is the port number you entered in the container configuration. - Alternatively, if you configured the MySQL port forwarding, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.
Installing the Image on macOS or Linux using Docker Desktop
This installation method doesn't provide data protection if the container is accidentally deleted. We don't recommend it if you are planning to convert the installation to a fully functional development environment for a client's project.
- Install and launch Docker Desktop for macOS or Linux.
-
Launch Terminal and run
docker pull octobercms/october-dev:latest - In Docker Desktop, go to Images, find the pulled image, and click Run.
- In the container configuration popup, click Optional Settings.
- Enter the container name, e.g. my-octobercms-test. If you skip that step, a container name will be generated automatically.
- Click the Plus icon in the Ports section to reveal settings for the port 80.
- Enter a forwarding port number for the container's port 80. You will use this port to access the installation in a browser. You can use 8080 or a similar value. Remember that you can't have two running containers that use the same port number. We recommend using a unique port number for every container.
- Optionally, enter a forwarding port number for the MySQL port 3306. You can use that port to connect to the MySQL server running in the container.
- Click Run to start the container.
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. This limitation doesn't exist in other installation methods.
Editing files in the container
You can access files in the container using the Remote-Containers extension for Microsoft Visual Studio Code.
- Install the extension.
- Open the Command Palette (
cmd+shift+p) and select Remote-Containers: Attach to Running Container. - Select your container.
- That will open a new Code window. Click the Open Folder button in the sidebar and select the
/var/www/htmldirectory.
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 commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
Git is pre-installed in the Image, and you can clone and push code from inside the container. The user.name and user.email git configuration parameters are automatically copied into the container by the Visual Studio Code extension. To use SSH keys, you may need to configure the SSH agent on the host computer. Read the Remote-Containers extension documentation to learn how to configure SSH. With other installation methods, you can pull and push files from your host machine as you usually do.
Accessing the MySQL database
The MySQL 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 MySQL 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. Theportargument is the port number you entered in the container configuration. - Alternatively, if you configured the MySQL port forwarding, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.
Installing the Image on macOS or Linux using the interactive bash script
This option stores files and the database on the host computer. This protects you from losing your work if you accidentally delete the container.
- Install Docker Desktop for macOS or Linux.
- Launch Terminal and create a new directory, e.g.
mkdir -p ~/october/my-octobercms-project - Enter the new directory
cd ~/october/my-octobercms-project - Run the interactive script:
bash -c "$(curl https://octobercms.com/api/dockerdevinstaller)" - Enter the forwarding port numbers for HTTP and MySQL. Remember that you can't have two running containers that use the same port numbers. We recommend using a unique port number for every container.
- Enter the container name and wait until the container is ready. Depending on your computer’s performance, it can take several minutes.
After the container starts, you should be able to access the installation in a browser, e.g. http://localhost:8081.
The script creates two directories:
octobercms-files- contains the October CMS installation files. You can edit the files directly, or use the Remote - Containers extension for Visual Studio Code (see below).octobercms-database- contains the database files.
Using the Image
After creating the container, you can control it on the Containers / Apps tab in Docker Desktop.
Editing files in the container
As the files are hosted on your computer, you can edit them directly by opening the project directory in your favorite editor. Alternatively, you can use the Remote-Containers extension for Microsoft Visual Studio Code.
Running CLI commands in the container
If you use the Remote-Container extension for Microsoft Visual Studio Code, the Remote-Containers: Attach to Running Container command 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.
Alternatively you can use the Docker extension for Microsoft Visual Studio Code. The extension allows you to attach the Code Terminal to a running container.
- Install the extension.
- Open the Command Palette (
cmd+shift+p) and select Docker Containers: Attach Shell. - Select your container.
- That will open the Terminal panel attached to the container.
In the Terminal you can run any CLI commands, including Artisan commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
Since the application files are hosted on your computer, you can use git as you usually do.
Rebuilding the container
If for any reason, the application container is broken or deleted, you can rebuild it without losing your application files and database.
- In the Terminal, go to the installation directory.
- Start the installation script:
bash -c "$(curl https://octobercms.com/api/dockerdevinstaller)". The script will detect that theoctobercms-filesanddatabase-filesdirectories already exist and will use them for the container. - Complete the installation and wait until the container is ready.
Accessing the MySQL database
The MySQL 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 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. Theportargument is the port number you entered in the container configuration. The connection string was displayed in the interactive script output. - Alternatively, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.
Installing the Image on Windows using the interactive bash script
This option stores files and the database on the host computer. This protects you from losing your work if you accidentally delete the container.
To run the Image on Windows you will need to use WSL 2 (Windows Subsystem for Linux). Follow the instructions from Microsoft and make sure you use WSL 2. This tutorial assumes you use Ubuntu distribution. To simplify the file permissions setup, you can configure Ubuntu to use root as the default account. To do so, run the following command in Windows Command Prompt: ubuntu config --default-user root
- Install Docker Desktop for Windows.
- Start Ubuntu from Windows Start menu.
- In Ubuntu Terminal, create a directory for your October CMS project, e.g.
mkdir -p /var/october/my-octobercms-project - Enter the new directory
cd /var/october/my-octobercms-project - Run the interactive script:
bash -c "$(curl https://octobercms.com/api/dockerdevinstaller)" - Enter the forwarding port numbers for HTTP and MySQL. Remember that you can't have two running containers that use the same port numbers. We recommend using a unique port number for every container.
- Enter the container name and wait until the container is ready. Depending on your computer’s performance, it can take several minutes.
After the container starts, you should be able to access the installation in a browser, e.g. http://localhost:8081.
You can access the project directory in Windows Explorer using the WSL mount, for example: \\wsl$\Ubuntu\var\october\my-octobercms-project. The script creates two directories:
octobercms-files- contains the October CMS installation files. You can edit the files directly, or use the Remote - Containers extension for Visual Studio Code (see below).octobercms-database- contains the database files.
Using the Image
After creating the container, you can control it on the Containers / Apps tab in Docker Desktop.
Editing files in the container
As the files are hosted on your computer, you can edit them directly by opening the project directory in your favorite editor.
You can launch Visual Studio Code from the Ubuntu terminal using the code command. The editor will open the current directory.
Alternatively, you can use the Remote-Containers extension for Microsoft Visual Studio Code.
Running CLI commands in the container
If you use the Remote-Container extension for Microsoft Visual Studio Code, the Remote-Containers: Attach to Running Container command 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.
Alternatively you can use the Docker extension for Microsoft Visual Studio Code. The extension allows you to attach the Code Terminal to a running container.
- Install the extension.
- Open the Command Palette (
ctrl+shift+p) and select Docker Containers: Attach Shell. - Select your container.
- That will open the Terminal panel attached to the container.
In the Terminal you can run any CLI commands, including Artisan commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
You might want to configure git in your Ubuntu distribution. Please follow the instructions from Microsoft.
Rebuilding the container
If for any reason, the application container is broken or deleted, you can rebuild it without losing your application files and database.
- In the Ubuntu Terminal, go to the installation directory.
- Start the installation script:
bash -c "$(curl https://octobercms.com/api/dockerdevinstaller)". The script will detect that theoctobercms-filesanddatabase-filesdirectories already exist and will use them for the container. - Complete the installation and wait until the container is ready.
Accessing the MySQL database
The MySQL 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 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. Theportargument is the port number you entered in the container configuration. The connection string was displayed in the interactive script output. - Alternatively, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.
Installing the Image manually
This installation method can provide data protection depending on the configuration.
For the manual installation, we assume you know how to use Docker and Windows WSL. You can create the container using Docker Desktop or from the command line.
The container exposes two ports which you can choose to forward:
- Port
80- for accessing the application from a browser. - Port
3306- for accessing the MySQL server running in the container.
The container has two directories you may want to map to your host machine directories:
/var/www/html- the installation root directory. If the mapped directory is empty, the container copies October CMS files to it on the first launch. If the directory is not empty, the container assumes the application is already installed. It's a part of the data protection mechanism./var/lib/october-mysql- MySQL files. Similarly to the previous directory, you can map it to your host machine. If the directory is empty, the container will copy MySQL database files to it. Otherwise, it will use files existing in the directory.
Using the Image
After creating the container, you can control it on the Containers / Apps tab in Docker Desktop.
Editing files in the container
Depending on your host platform and whether you mapped /var/www/html to your host machine directory, you can edit files directly or using the Remote-Containers extension for Microsoft Visual Studio Code.
Running CLI commands in the container
If you use the Remote-Container extension for Microsoft Visual Studio Code, the Remote-Containers: Attach to Running Container command 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.
Alternatively you can use the Docker extension for Microsoft Visual Studio Code. The extension allows you to attach the Code Terminal to a running container.
- Install the extension.
- Open the Command Palette (
ctrl+shift+p) and select Docker Containers: Attach Shell. - Select your container.
- That will open the Terminal panel attached to the container.
In the Terminal you can run any CLI commands, including Artisan commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
Accessing the MySQL database
The MySQL 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 MySQL 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. Theportargument is the port number you entered in the container configuration. - Alternatively, if you configured the MySQL port forwarding, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.
Installing the Image manually
This installation method can provide data protection depending on the configuration.
For the manual installation, we assume you know how to use Docker. You can create the container using Docker Desktop or from the command line.
The container exposes two ports which you can choose to forward:
- Port
80- for accessing the application from a browser. - Port
3306- for accessing the MySQL server running in the container.
The container has two directories you may want to map to your host machine directories:
/var/www/html- the installation root directory. If the mapped directory is empty, the container copies October CMS files to it on the first launch. If the directory is not empty, the container assumes the application is already installed. It's a part of the data protection mechanism./var/lib/october-mysql- MySQL files. Similarly to the previous directory, you can map it to your host machine. If the directory is empty, the container will copy MySQL database files to it. Otherwise, it will use files existing in the directory.
Using the Image
After creating the container, you can control it on the Containers / Apps tab in Docker Desktop.
Editing files in the container
Depending on your host platform and whether you mapped /var/www/html to your host machine directory, you can edit files directly or using the Remote-Containers extension for Microsoft Visual Studio Code.
Running CLI commands in the container
If you use the Remote-Container extension for Microsoft Visual Studio Code, the Remote-Containers: Attach to Running Container command 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.
Alternatively you can use the Docker extension for Microsoft Visual Studio Code. The extension allows you to attach the Code Terminal to a running container.
- Install the extension.
- Open the Command Palette (
cmd+shift+p) and select Docker Containers: Attach Shell. - Select your container.
- That will open the Terminal panel attached to the container.
In the Terminal you can run any CLI commands, including Artisan commands. Run php artisan to see the list of available commands. Until the installation is licensed you can't run composer update, composer install and php artisan october:update.
Accessing the MySQL database
The MySQL 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 MySQL 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. Theportargument is the port number you entered in the container configuration. - Alternatively, if you configured the MySQL port forwarding, you can use any MySQL GUI tool, for example, MySQL Workbench.
Licensing the Container
To remove all limitations from the container, please follow instructions from the Licensing the Development Docker Container page.