Easily bootstrap a new October CMS project
oc-bootstrapper is a simple script that enables you to bootstrap an October CMS installation
with custom plugins and custom themes. You simply describe your setup in a config file and run
the install command.
oc-bootstrapper enables you to install plugins and themes from your own git repo.
The following steps will be taken care of:
- The latest October CMS gets downloaded from github and gets installed
- All composer dependencies are installed
- Relevant config entries are moved to a
.envfile for easy customization
- Sensible configuration defaults for your
prodenvironment get pre-set
- Your database gets migrated
- All demo data gets removed
- Your selected theme gets downloaded and installed
- All your plugins get downloaded and installed
- A .gitignore file gets created
- A push to deploy setup gets initialized for you
- Zip PHP extension (
sudo apt-get install php7.0-zip)
- Composer (via global binary or
composer.pharin your working directory)
- Ubuntu 15.10
- Ubuntu 16.04
- OSX 10.11 (El Capitan)
Will probably not work on Windows.
composer global require mrelevance/oc-bootstrapper
You can now run
october from your command line.
$ october October CMS Bootstrapper version 0.2.0
october init command to create a new project with a config file:
october init myproject.com cd myproject.com
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 (email@example.com) edgeUpdates: false enableSafeMode: false database: connection: mysql username: homestead password: secret database: bootstrapper host: 192.168.10.10 git: deployment: false bareRepo: true # Exclude everything except themes and custom plugins in git excludePlugins: false # Even exclude plugins from your repo. Private plugins will be # checkout out again during each "install" run. Be careful! # Manual changes to these plugins will be overwritten. plugins: - Rainlab.Pages - Rainlab.Builder - Indikator.Backend - OFFLINE.SiteSearch - OFFLINE.ResponsiveImages - OFFLINE.Indirect (https://github.com/OFFLINE-GmbH/oc-indirect-plugin.git) # - Vendor.Private (firstname.lastname@example.org) # - Vendor.PrivateCustomBranch (email@example.com#branch) mail: host: smtp.mailgun.org name: User Name address: firstname.lastname@example.org driver: log
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.
When you are done editing your configuration file, simply run
october install to install October.
If at any point in time you need to install additional plugins, simply add them to your
october.yaml and rerun
october install. Missing plugins will be installed.
To change your installation's configuration, simply edit the
.env file in your project root.
When deploying to production, make sure to edit your
.env.production template file and rename it to
If you don't want to have the complete October source code in your repository set the
This will set up a
.gitignore file that excludes everything except your
theme directory and all the manually installed plugins in your
If you want to deploy a bare repo please read the section
SSH deployments with bare reposbelow.
By default every private plugin will be cloned only once and is then added to your
.gitignore file. In the end your bare repo includes your theme and all your custom and private plugins. If you wish to only include your theme and no plugin data at all you can set
excludePlugins to true.
If you run
october install in an existing project (let's say during deployment) all private plugin directories will get remove from your local disk and are checked out via git again so you'll get the latest version.
If you don't want a plugin to be checked out on every
october install run you can add the following line to your
.gitignore file. If such a line is found the plugin will not be touched after the first checkout.
# vendor.plugin # offline.sitesearch
After cloning a bare repo for the first time, simply run
october install. October CMS and all missing plugins will get installed locally on your machine.
deployment option to
false if you don't want to setup deployments.
oc-bootstrapper supports a simple setup to deploy a project on push via GitLab CI. To automatically create all needed files, simply set the
deployment option to
Support for other CI systems is added on request.
If you use SSH deployments with a bare repo, make sure to run
./vendor/bin/october install in your deployment script to install the October source code and all of your plugins . If the October source code is already available it won't be downloaded again.
If you use the provided GitLab deployment via Envoy make sure to simply uncomment this line.
It is important that you list every installed plugin in your
october.yaml file. Otherwise the plugins won't be available after deployment.
If you use the gitlab deployment option the
Envoy.blade.php files are created for you.
Change the variables inside the
Envoy.blade.php to fit your needs.
If you push to your GitLab server and CI builds are enabled, the ssh tasks inside
Envoy.blade.php are executed. Make sure that your GitLab CI Runner user can access your target server via
ssh user@targetserver. You'll need to copy your ssh public key to the target server and enable password-less logins via ssh.
For more information on how to use ssh keys during a CI build see http://doc.gitlab.com/ce/ci/ssh_keys/README.html
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
git.cron.sh every X minutes. This script will commit all changes
to your git repo automatically.
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
~/.composer/october. All files from the
templates directory can be overwritten.
- Update command to update private plugins
If you are working with XAMPP on Windows you will most likely get the following error during
cURL error 60: SSL certificate problem: unable to get local issuer certificate
You can fix this error by executing the following steps.
cacert.pemfile from VersatilityWerks
phpfolder in your xampp directory (eg.
C:\xampp\php\php.ini). Add the following line.
curl.cainfo = "\xampp\php\cacert.pem"
october install should work now as expected.