Bootstrapper for October CMS
oc-bootstrapper is a command line tool that enables you to reconstruct an October CMS installation
from a single configuration file.
It can be used to quickly bootstrap a local development environment for a project or to build and update a production installation during a deployment.
- Installs and updates private and public plugins (via Git or Marketplace)
- Makes sure only necessary files are in your git repo by intelligently managing your
- Built in support for GitLab CI deployments
- Built in support for shared configuration file templates
- Sets sensible configuration defaults using
.envfiles for production and development environments
- Zip PHP extension (
sudo apt-get install php-zip)
- Composer (via global binary or
composer.pharin your working directory)
- Ubuntu 15.10
- Ubuntu 16.04
- Ubuntu 18.04
- OSX 10.11 (El Capitan)
Works on Windows via
Ubuntu Bash or
oc-bootstrapper it is a good idea to keep
october.yaml, project's theme and project's plugins (those that are not shared among other projects) in project's repo.
Take a look at the OFFLINE-GmbH/octobertricks.com repo to see an example setup of
composer global require offline/oc-bootstrapper
You can now run
october from your command line.
$ october -v October CMS Bootstrapper version 0.5.0
An official Docker image that bundles
Envoy is available on hub.docker.com as
docker run offlinegmbh/oc-bootstrapper october -v docker run offlinegmbh/oc-bootstrapper envoy -v docker run offlinegmbh/oc-bootstrapper composer -v
Initialize your project
october init command to create a new empty project with a config file:
october init myproject.com cd myproject.com
Change your configuration
In your newly created project directory you'll find an
october.yaml file. Edit its contents
to suite your needs.
app: url: http://october.dev locale: en debug: true cms: theme: name (firstname.lastname@example.org) edgeUpdates: false disableCoreUpdates: false enableSafeMode: false # project: XXXX # Marketplace project ID database: connection: mysql username: root password: database: bootstrapper host: localhost git: deployment: gitlab plugins: - Rainlab.Pages - Rainlab.Builder - Indikator.Backend - OFFLINE.SiteSearch - OFFLINE.ResponsiveImages - OFFLINE.GDPR (https://github.com/OFFLINE-GmbH/oc-gdpr-plugin.git) - ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop) # - Vendor.Private (email@example.com) # - Vendor.PrivateCustomBranch (firstname.lastname@example.org#branch) mail: host: smtp.mailgun.org name: User Name address: email@example.com driver: log
Theme and Plugin syntax
oc-bootstrapper enables you to install plugins and themes from your own git repo. Simply
append your repo's address in
() to tell
oc-bootstrapper to check it out for you.
If no repo is defined the plugins are loaded from the October Marketplace.
# Install a plugin from the official October Marketplace - OFFLINE.Mall # Install a plugin from a git repository. The plugin will be cloned # into your local repository and become part of it. You can change the # plugin and modify it to your needs. It won't be checked out again (no updates). - OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git) # The ^ marks this plugin as updateable. It will be removed and checked out again # during each call to `october install`. Local changes will be overwritten. # This plugin will stay up to date with the changes of your original plugin repo. - ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git) # Install a specific branch of a plugin. Keep it up-to-date. - ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop)
Install October CMS
When you are done editing your configuration file, simply run
october install to install October.
oc-bootstrapper will take care of setting everything up for you. You can run this command locally
after checking out a project repository or during deployment.
This command is idempotent, it will only install what is missing on subsequent calls.
--help flag to see all available options.
october install --help
Install additional plugins
If at any point in time you need to install additional plugins, simply add them to your
october.yaml and re-run
october install. Missing plugins will be installed.
Use a custom php binary
--php flag you can specify a custom php binary to be used for the installation commands:
october install --php=/usr/local/bin/php72
Update October CMS
If you want to update the installation you can run
Push changes to remote git repo
To push local changes to the current git remote run
This command can be run as cron job to keep your git repo up-to-date with changes on production.
deployment option to
false if you don't want to setup deployments.
You can use
oc-bootstrapper with any kind of deployment software. You need to setup the following steps:
- Connect to the target server (via SSH)
- Install composer and oc-bootstrapper
You can run this "script" for each push to your repository. The
october install command will
only install what is missing from the target server.
Example setup for GitLab CI
To initialize a project with GitLab CI support set the
deployment option in your config file to
- Create a SSH key pair to log in to your deployment target server
- Create a
SSH_PRIVATE_KEYvariable in your GitLab CI settings that contains the created private key
- Edit the
Envoy.blade.phpscript to fit your needs
- Push to your repository. GitLab will run the example
Cronjob to commit changes from prod into git
If a deployed website is edited by a customer directly on the prod server you might want to commit those changes back to your git repository.
To do this, simply create a cronjob that executes
october push every X minutes. This command will commit all changes
to your git repo automatically with message
[ci skip] Added changes from $hostname.
You can overwrite all default file templates by creating a folder called
october in your global composer directory.
Usually it is located under
Place the files you want to use as defaults in
~/.config/composer/october. All files from the
templates directory can be overwritten.
On Windows you can store your files in
File templates from a git repository
If your templates folder is a git repository
oc-bootstrapper will pull the latest changes for the repo every time
This is a great feature if you want to share the template files with your team via a central
git repository. Just make sure you are able to fetch the latest changes via
git pull and you're all set!
cd ~/.config/composer/october git clone your-central-templates-repo.git . git branch --set-upstream-to=origin/master master git pull # Make sure this works without any user interaction