Docker-based deployment for October CMS with a simple CLI interface.

# Clone the repository
git clone https://github.com/yourusername/october-docker.git
cd october-docker

# Set up a new site
./october-setup myapp

# Start the site
./launcher start myapp

Your site will be available at http://localhost

• Docker Engine 20.10+
• Docker Compose v2
• WSL2 (Windows) or native Linux/macOS

october-docker/                    # This repository (clone once)
├── containers/                    # Site configurations
│   └── myapp.yml
├── docker/                        # Docker infrastructure
│   └── web/
│       ├── Dockerfile
│       └── ...
├── launcher                       # CLI tool
├── october-setup                  # Setup wizard
└── docker-compose.base.yml

~/october-sites/myapp/             # Your site files
├── .env                           # Environment variables
├── .data/                         # Database & Redis data
│   ├── mysql/
│   └── redis/
├── artisan                        # October CMS files
├── composer.json
└── ...

• Xdebug enabled for debugging
• APP_DEBUG=true
• OPcache validates timestamps
• Bundled MariaDB and Redis

• Xdebug disabled
• APP_DEBUG=false
• OPcache optimized
• SSL via Let's Encrypt or custom certificates
• Option to use external database (AWS RDS) and Redis (ElastiCache)

Run multiple October sites from one installation:

./october-setup blog
./october-setup shop --port 8080
./october-setup corporate --port 8081

./launcher start blog
./launcher start shop
./launcher start corporate

Each site has isolated containers and data directories.

Open VS Code attached to a running site container:

./launcher code myapp

This opens VS Code with the Dev Containers extension connected directly to the web container, giving you:

• Full IDE with IntelliSense
• Integrated debugging with Xdebug
• Terminal access inside the container

On Windows, site files live inside WSL2 for optimal Docker volume performance. To access them with Windows tools like Tortoise Git, the launcher can mount the sites directory as a Windows drive via Samba:

./launcher mount

This will:

1. Install Samba in WSL if needed (one-time)
2. Configure a share for ~/october-sites
3. Ask for a drive letter (default: Z)
4. Mount the drive automatically

Your sites will be available at Z:\myapp, Z:\blog, etc. Use Tortoise Git, Explorer, and other Windows tools normally.

To disconnect:

./launcher unmount

The WSL IP changes on reboot, so you'll need to run ./launcher mount each time you restart your machine.

To deploy from your own October CMS repository instead of a fresh install:

1. During setup, select "Yes" for custom Git repository
2. Enter your repository URL
3. Optionally specify a branch (leave empty for the default branch)
4. The entrypoint will clone your repo and run composer install

Or manually set OCTOBER_REPO and OCTOBER_BRANCH in your site's .env file before first start.

To install October CMS v3 from the official repository:

# Set up a new site
./october-setup myapp

During setup, select "Yes" for custom Git repository and enter:

• Repository URL: https://github.com/octobercms/october.git
• Branch: 3.x

Then start the site:

./launcher start myapp

On first start, the container will clone the repository, check out the 3.x branch, and run composer install. Once the containers are running, open a shell to complete the installation:

./launcher enter myapp
php artisan october:install
php artisan october:migrate
php artisan october:mirror

This will run the interactive installer where you can enter your license key and configure the application. You only need to do this once.

environment: development
site_path: ~/october-sites/myapp
http_port: 80

services:
  mariadb: true
  redis: true

Generated automatically by october-setup. Contains:

• APP_KEY, APP_URL, APP_ENV
• Database credentials
• Redis configuration

• PHP: 8.3 with FPM
• Web Server: Apache with HTTP/2
• Database: MariaDB 10.11
• Cache: Redis 7
• Process Manager: Supervisor

./launcher logs myapp

Check that MariaDB is healthy:

docker ps

The web container waits for MariaDB to be ready before running migrations.

The container runs as www-data. If you have permission issues with mounted files:

./launcher enter myapp
chown -R www-data:www-data /var/www/html/storage

If accessing files via \\wsl.localhost\ or a mapped drive shows permission errors, use the Samba mount instead:

./launcher mount

Samba bypasses Linux file permissions, so files are always writable regardless of ownership.

If a mapped drive letter persists in Explorer after unmounting, restart Explorer:

Stop-Process -Name explorer -Force; Start-Process explorer

./launcher destroy myapp
rm -rf ~/october-sites/myapp
./october-setup myapp
./launcher start myapp

MIT