This forum has moved to a new location and is in read-only mode. Please visit to access the new location.


Between us I'm hoping we can come up with a best practise for deploying October as I've recently had a complete nightmare just deploying to a staging server - components not loading, component default partials loading instead of ones in theme, general errors, paths not working. The only way I've been able to successfully deploy is as below but I think this is ridiculous.

  1. Install October on staging server using composer
  2. Manually copying across plugins and custom theme
  3. Updating required bits in app/config (key, theme, url, db details -- see below)
  4. Running php artisan october:up
  5. Update app/config/database.php to use getenv() variables (can't do this in step 3 as artisan doesn't recognise them) -- see below

What I'd quite like to be able to do, and maybe ignorantly doesn't understand why it can be done, is just pull from my repo but this is full of problems which it seems separately installing October fixes.

I'm not brilliant with git so is there a better way to version control what I'm doing? Should I just be included my plugins/themes directory? I don't like this idea as ideally I want to be running the same core code across servers. Maybe I'm not ignoring everything I should be (basically the app/storage directory and app/config/database.php). I also want to be able to make use of the deploy option in Forge and not have to spend too much time working out how to get a deployed version of October to work.

I'm open to ideas and willing to try things if people have suggestions. Has anyone successfully deployed from their own repo? Seems to me it should work with little updates.

Also anyone know why artisan can't find environment variables? That would at least cross off step 5.

Answer: Worked it out environment variables - Forge installs .env.php file in root, not in public directory so it has to be moved into public for artisan to see it.



Last updated


Seems to be a popular topic. Everyone has their own workflow, but it's certainly not apparent what the best option(s) are initially coming over from wordpress or other framework development like I did. It's the one part of October I've yet to find a fully elegant solution for still.


Thanks for cross link 406digital. Just vc'ing themes wouldn't work for me. Andrew seems to have luck his way so I might give that a bash, but previously have had a lot of problems (might not have excluded everything).


We really need to be able to smoothly deploy to laravel forge. Ideally we push to a git repo and it is deployed to the forge cloud servers from there. Adam were you able to smooth out any more steps of your deployment process?


Hi Jon,

I'm still ironing it out. Basically I only commit plugins and themes folder. On server you have to be a bit funky because of the file based aspect of October so in Forge my deploy script is this:

git stash
git pull origin master
git stash pop

This may be a bit of an abuse for stash but couldn't figure another way of pulling without overwriting the files in the public directory that need to be kept (i.e. all the October ones!). I'm then going to add a gitignore to the server to ignore all directories that have files saved by front end users - this is going to vary depending on your setup but for me will mainly be the dirs that contain the pages plugin content files and menu yaml files. I haven't done this yet as I've not needed to but probably will be doing it this week. Can't see why that wouldn't work but it might not!

Last updated


Why are you stashing the changes instead of committing them to the repo? Is that stash on the live server? If it is you kinda want those changes pushed back up to the repo.


I wasn't using stash to stash changes but to keep everything that isn't in git. If I hadn't stashed I'd have lost everything except the plugins and themes directories that are in version control.

I stopped doing that and I've gone back to manually copying files across to live environment.

Sebastian Hilger
Sebastian Hilger

For anyone who's interested, here is my workflow for :

  • Having a working test website locally
  • Deploying to my production website via Forge (This is a simple setup, no staging server is used).

1) make new empty repo in github

2) clone repo to local system

3) make new forge site:

  • remove "public" Web Directory
  • make site
  • uncheck "Install Composer Dependencies" repository
  • install repo
  • edit deploy script: remove 2 lines:

    composer install --no-interaction --no-dev --prefer-dist
    php artisan migrate --force
  • add line:
    php artisan october:up

4) download october installer on local system

5) push to github

6) deploy once in forge

7) Install a site locally and install a site on your forge location ("from scratch")

8) Delete install.php and /install_files locally and on your forge location

9) change gitignore locally:


10) Turn on Quick Deploy in Forge

11) Start coding your custom themes and custom plugins locally and push to deploy whenevev you like.

Using gulp, bower etc:

I personally use sass, bower and gulp in my theme assets folder. If you'd like to do something similar, make sure to gitignore the source folders for your sass/css, and also you js (if you use gulp to combine your js files like me) and publish only your destination folders for css and js. I my case this looks like this in my gitignore file at root level - in your case of course things might differ, and of course you could use gitinore files in the respective folders (I just like to have everything in one place):

/themes/[your theme name]/assets/src
/themes/[your theme name]/assets/vendor
/themes/[your theme name]/assets/node_modules
/themes/[your theme name]/assets/.bowerrc
/themes/[your theme name]/assets/bower.json
/themes/[your theme name]/assets/gulpfile.js
/themes/[your theme name]/assets/package.json

Using third party PHP in your custom plugin:

I often need to include third party libraries that are not included in October CMS. This is how I do it: Locally I use composer in my plugin folder to install the libaries. Then I make sure composer.json and composer.lock are gitignored:

/plugins/[your author name]/[your plugin name]/composer.json
/plugins/[your author name]/[your plugin name]/composer.lock

Everytime push to deploy, the third party libraries are also pushed.

Of course this is just one way of doing it - and when I work on a Laravel app without October CMS I would not do it this way, but instead gignore my vendor file and publish my composer.lock file and let composer on the production server install the dependencies, but when working with October I found it easier to not have running composer on the production server.

Hope this helps someone.

Last updated


Have a look at oc-bootstrapper. It provides some sample scripts to setup a simple push to deploy system via GitLab CI and Laravel Envoy. You can modify the scripts to support other CI systems.

I suggest adding everything (plugins and themes) to your repository. Then deploy those to your prod server via Envoy's ssh tasks. On your prod server run a cronjob that triggers a bash script which commits the changes back to your git repository.

This way the repository is the only "source of truth".

To go even further you could create a db dump and import it on prod/dev during this process.

Last updated


I like the approach of @sebastian-hilger but, how to handle backend changes to themes, pages, content, etc? This is not stored on db

Sebastian Hilger
Sebastian Hilger

@maxacarvalho my private themes and plugins are not gitignored, so they are part of version control.


@sebastian-hilger yes, this is a solution. But my questions is, what about when some change is made using the backend? For example, is a change is made in a page using the backend? In that case the .htm would be changed, how to keep track of that change?


I don't know if this will help anyone else but this is the solution I've been running with. I run a bunch of my own private packages on that are stored in bitbucket. I created a satis repository that helped link to those repositories so I can use composer to include them outside of packagist. In each plugin's composer.json you need to set it as type "october-plugin" and then require "composer/installers": "~1.0". These are stored as their own repository as reusable site components. Then I create a repository for my theme plugin that I'm going to use. You should set the type to "october-theme" and require composer installers again as well as the plugins you plan on incorporating. Rough example below,

"require": {

   "composer/installers": "~1.0",

   "freemedical/content": "dev-master",

   "freemedical/shop": "dev-master",

   "freemedical/banners": "dev-master"


From there my install process looks like this:

1) Install octobercms through composer.

2) Add in my satis repository to composer so that I can use my private package references

3) Pull environment variables to .env and configure them.

4) Use composer to require my theme: composer require freemedical/websitetheme

  • This will install my theme and it'll also go through and install all of my required dependencies from my theme's composer.json and all of the plugins' package dependencies as well.

5) php artisan october:up to run migrations.

6) At this point you have a functioning website. If you really need to, you can copy the database and storage directory over and have an exact clone of another environment.

As far as modifying pages and .htm files you really want to either create a plugin that defines hotspots to fill in front end content or investigate the rainlab/pages plugin for static content. I'd try and make all user modifications database driven so that your source is never touched. An example on one of my sites might be a partial that adds in my content component that defines a typing area so that a client can modify a blurb on their about us page.

I'm still relatively new in my OCMS production site journey (only have 1-2 up) but what I have has worked pretty well so far.

Last updated

Sebastian Hilger
Sebastian Hilger

maxacarvalho said:

@sebastian-hilger yes, this is a solution. But my questions is, what about when some change is made using the backend? For example, is a change is made in a page using the backend? In that case the .htm would be changed, how to keep track of that change?

Ah yeah - sorry, as I never use the CMS part of October like that, the User never actually touches htm files. So I did not look into that problem yet.


@freemedical thanks for your detailed answer. Well, at the end, maybe is too much complexity. Maybe, it's better to: 1 - install October CMS 2 - Disable auto updates on prod 3 - Develop your own Plugin and push into the application using the normal flow 4 - Develop your own Themes and push into the application using the normal flow 5 - Keep backups of the server 6 - Maintain copies of the environment (local dev, project, staging, ...) 7 - Test updates and new features on the copy environments 8 - Push the updates to production using the normal flow


Thank you all for your ideas.

@maxacarvalho Your 1-8 plan looks good. For us newbies, would you expand on what you mean in each case (3, 4 and 8) by "using the normal flow".


Hi @alanq Here is what I think:

  1. Install October CMS I don't think this step needs too much explanation. Just the normal installation process
  2. Disable auto-updates on prod I believe this is necessary in order to test new updates. Maybe a core, plugin, theme update can break your site so, is always better to test first in a different environment
  3. Develop your own plugin(s) If you need some feature and there is not a suitable plugin for that, you will need to develop one. I believe that the best thing to do in this situation is to build your plugin, publish to the October MarketPlace and install in your site. so every time that you update your plugin you can update your website to fetch the latest changes
  4. Develop your own themes: Similar to the plugin development, if you cannot find a suitable theme you need to develop one, push to October MarketPlace and install it on your site. Or you can develop the entire theme using the October CMS backend.
  5. Keeps backups This is self-explanatory
  6. Maintain copies of the environment Well, this really depends on how big your project is. Normally a development environment (can be local environment) and production will work fine.
  7. Test updates and new features on test environment It's always better to test a plugin update, or a theme change in a development environment so you don't mess up with the production website
  8. Push the updates to production So, after testing the plugins updates, new features, big theme changes, on the development environment. You propagate the changes to production site using.


  • If you are using October mirror feature on production (and you should) it's always better to install updates using the command line. Using the backend can bring some problems because of the directories that are not mirrored.

most wanted feature:

  • Private OctoberCms MarketPlace: Would be extremely helpful to have private MarketPlace, not always you want to make your theme or plugin available to everyone. It's not a selfish feature request, sometimes you need to protect you business rules.

Thank you, @maxacarvalho, especially for the advice.

It would appear that the holy grail of easy deployment is still to be created.


I know that every environment and set of requirements is different, but for a from-scratch setup, I've created the following guide:

It's what I use as a reference implementation for OctoberCMS. Latest Ubuntu, SSL certificate, sane security defaults, and minimal setup time. I ran through the guide now, copying and pasting snippets as I went, and was able to go from zero to CMS in just under 11 minutes.

I haven't really tried using the git-based deployment method yet - to be honest I prefer the web installer, since it adds one extra level of validation: You need to be able to reach the web installer in order to use it, so it's a free check that your web server is actually working as expected.


Thank you, @woganmay

Looks like a well-written guide with some useful info and pointers.

However, the issue here is not installation, it is deployment: moving a site from one server to another.

Most especially, when you have a live site and a development site, how to transfer changes in the development site to the live site without breaking anything on the live site.

...and without spending more time and effort than it took to develop the site in the first place ;)

1-20 of 27

You cannot edit posts or make replies: the forum has moved to