{"id":28656078,"url":"https://github.com/offline-gmbh/oc-bootstrapper","last_synced_at":"2025-06-13T08:10:15.975Z","repository":{"id":50521886,"uuid":"52451802","full_name":"OFFLINE-GmbH/oc-bootstrapper","owner":"OFFLINE-GmbH","description":"Easily bootstrap a new October CMS project","archived":false,"fork":false,"pushed_at":"2021-06-14T06:14:07.000Z","size":332,"stargazers_count":81,"open_issues_count":9,"forks_count":25,"subscribers_count":12,"default_branch":"develop","last_synced_at":"2025-05-31T10:26:24.962Z","etag":null,"topics":["bootstrapper","octobercms","utility"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OFFLINE-GmbH.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-24T15:17:35.000Z","updated_at":"2024-11-21T23:15:25.000Z","dependencies_parsed_at":"2022-08-23T17:40:49.322Z","dependency_job_id":null,"html_url":"https://github.com/OFFLINE-GmbH/oc-bootstrapper","commit_stats":null,"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/OFFLINE-GmbH/oc-bootstrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-bootstrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-bootstrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-bootstrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-bootstrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OFFLINE-GmbH","download_url":"https://codeload.github.com/OFFLINE-GmbH/oc-bootstrapper/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OFFLINE-GmbH%2Foc-bootstrapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259606992,"owners_count":22883565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bootstrapper","octobercms","utility"],"created_at":"2025-06-13T08:10:14.982Z","updated_at":"2025-06-13T08:10:15.947Z","avatar_url":"https://github.com/OFFLINE-GmbH.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bootstrapper for October CMS\n\n`oc-bootstrapper` is a command line tool that enables you to reconstruct an October CMS installation\nfrom a single configuration file.\n\nIt can be used to quickly bootstrap a local development environment for a project or\nto build and update a production installation during a deployment.\n\n\n## Features\n\n* Installs and updates private and public plugins (via Git or Marketplace)\n* Makes sure only necessary files are in your git repo by intelligently managing your `.gitignore` file\n* Built in support for GitLab CI deployments\n* Built in support for shared configuration file templates\n* Sets sensible configuration defaults using `.env` files for production and development environments\n\n## Dependencies\n\n* Zip PHP extension (`sudo apt-get install php-zip`) \n* Composer (via global binary or `composer.phar` in your working directory) \n\n## Tested on\n\n* Ubuntu 15.10\n* Ubuntu 16.04\n* Ubuntu 18.04\n* OSX 10.11 (El Capitan)\n\nWorks on Windows via `Ubuntu Bash` or `Git Bash`.\n\n## Example project\n\nWhile using `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.\n\nTake a look at the [OFFLINE-GmbH/octobertricks.com](https://github.com/OFFLINE-GmbH/octobertricks.com) repo to see an example setup of `oc-bootstrapper`.\n\n## Installation\n\n```bash\ncomposer global require offline/oc-bootstrapper\n``` \n\nYou can now run `october` from your command line.\n\n```bash\n$ october -v\nOctober CMS Bootstrapper version 0.5.0\n```\n\n### Docker image\n\nAn official Docker image that bundles `oc-bootstrapper`, `composer` and `Envoy` is available on [hub.docker.com](https://hub.docker.com/r/offlinegmbh/oc-bootstrapper/) as `offlinegmbh/oc-bootstrapper`.\n\n```bash\ndocker run offlinegmbh/oc-bootstrapper october -v\ndocker run offlinegmbh/oc-bootstrapper envoy -v\ndocker run offlinegmbh/oc-bootstrapper composer -v\n```\n\nIt is intended to be used with CI pipelines but can also make getting started with an October project \neven easier as you don't need to install PHP and Composer locally.\n\nYou can execute any command in the context of the current working directory by using this docker command:\n\n```bash\n# alias this to \"october\" for easier access\ndocker run -it --rm -v \"$(pwd)\":/app offlinegmbh/oc-bootstrapper october\n```\n\nBe aware, that this will work great for commands like `october init` as it does not depend on any\nexternal services. To run `october install` some more plumbing is required so the container can connect\nto your database.\n\n## Usage\n\n### Initialize your project\n\nUse the `october init` command to create a new empty project with a config file:\n\n```sh\noctober init myproject.com\ncd myproject.com\n```\n\n### Change your configuration\n\nIn your newly created project directory you'll find an `october.yaml` file. Edit its contents\nto suite your needs.\n\n```yaml\napp:\n    name: my-new-project       # Give the project a unique name\n    url: http://october.dev\n    locale: en\n    debug: true\n\ncms:\n    theme: name (user@remote.git)\n    edgeUpdates: false\n    disableCoreUpdates: false\n    enableSafeMode: false\n    # project: XXXX            # Marketplace project ID\n\ndatabase:\n    connection: mysql\n    username: root\n    password: \n    database: bootstrapper\n    host: localhost\n\ngit:\n    deployment: gitlab\n    keepRepo: false       # Keep .git in plugins\n\n# deployment:            # Automatically configure the Envoy file for GitLab deployments      \n#     user: hostinguser  \n#     server: servername                    \n\nplugins:\n    - Rainlab.Pages\n    - Rainlab.Builder\n    - Indikator.Backend\n    - OFFLINE.SiteSearch\n    - OFFLINE.ResponsiveImages\n    - OFFLINE.GDPR (https://github.com/OFFLINE-GmbH/oc-gdpr-plugin.git)\n    - ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop)\n    # - Vendor.Private (user@remote.git)\n    # - Vendor.PrivateCustomBranch (user@remote.git#branch)\n\nmail:\n    host: smtp.mailgun.org\n    name: User Name\n    address: email@example.com\n    driver: log\n\n```\n\n#### Theme and Plugin syntax\n\n`oc-bootstrapper` enables you to install plugins and themes from your own git repo. Simply\nappend your repo's address in `()` to tell `oc-bootstrapper` to check it out for you.\nIf no repo is defined the plugins are loaded from the October Marketplace.\n\n##### Examples\n\n```yaml\n# Install a plugin from the official October Marketplace\n- OFFLINE.Mall \n\n# Install a plugin from a git repository. The plugin will be cloned\n# into your local repository and become part of it. You can change the\n# plugin and modify it to your needs. It won't be checked out again (no updates).\n- OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git)\n\n# The ^ marks this plugin as updateable. It will be removed and checked out again\n# during each call to `october install`. Local changes will be overwritten.\n# This plugin will stay up to date with the changes of your original plugin repo.\n- ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git)\n\n# Install a specific branch of a plugin. Keep it up-to-date.\n- ^OFFLINE.Mall (https://github.com/OFFLINE-GmbH/oc-mall-plugin.git#develop)\n```\n\n\n### Install October CMS\n\nWhen you are done editing your configuration file, simply run `october install` to install October. \n`oc-bootstrapper` will take care of setting everything up for you. You can run this command locally\nafter checking out a project repository or during deployment.\n\nThis command is *idempotent*, it will only install what is missing on subsequent calls. \n\n```\noctober install \n```\n\nUse the `--help` flag to see all available options.\n\n```\noctober install --help \n```\n\n#### Install additional plugins\n\nIf at any point in time you need to install additional plugins, simply add them to your `october.yaml` and re-run \n`october install`. Missing plugins will be installed.\n\n  \n\n#### Use a custom php binary\n\nVia the `--php` flag you can specify a custom php binary to be used for the installation commands:\n\n```\noctober install --php=/usr/local/bin/php72\n```\n### Update October CMS\n\nIf you want to update the installation you can run\n\n```\noctober update\n```\n### Push changes to remote git repo\n\nTo push local changes to the current git remote run \n\n```\noctober push\n```\n\nThis command can be run as cron job to keep your git repo up-to-date with changes on production.\n \n### SSH deployments\n\nSet the `deployment` option to `false` if you don't want to setup deployments.\n\n#### Setup\n\nYou can use `oc-bootstrapper` with any kind of deployment software. You need to setup the following steps:\n\n1. Connect to the target server (via SSH)\n1. Install composer and oc-bootstrapper\n1. Run `october install`\n\nYou can run this \"script\" for each push to your repository. The `october install` command will\nonly install what is missing from the target server.\n\n\n#### Example setup for GitLab CI\n\nTo initialize a project with GitLab CI support set the `deployment` option in your config file to `gitlab`.\n\nThis will setup a [`.gitlab-ci.yml`](templates/gitlab-ci.yml) and a [`Envoy.blade.php`](templates/Envoy.blade.php). \n\n1. Create a SSH key pair to log in to your deployment target server\n1. Create a `SSH_PRIVATE_KEY` variable in your GitLab CI settings that contains the created private key\n1. Edit the `Envoy.blade.php` script to fit your needs\n1. Push to your repository. GitLab will run the example `.gitlab-ci.yml` configuration\n\n\n### Cronjob to commit changes from prod into git\n\nIf a deployed website is edited by a customer directly on the prod server you might want to commit\n those changes back to your git repository. \n \nTo do this, simply create a cronjob that executes `october push` every X minutes. This command will commit all changes\nto your git repo automatically with message `[ci skip] Added changes from $hostname`.\n\n### File templates\n\nYou can overwrite all default file templates by creating a folder called `october` in your global composer directory.\nUsually it is located under `~/.config/composer`. \n\nPlace the files you want to use as defaults in `~/.config/composer/october`. All files from the `templates` directory can be overwritten.\n\nOn Windows you can store your files in `%USERPROFILE%/AppData/Roaming/Composer/october/`\n\n### Variable replacements\n\nIt is possible to use placeholders in your configuration files which will be replaced by \nvalues from your october.yaml configuration:\n\n```php\n// Example Envoy.blade.php\n$url = '%app.url%'; // Will be replaced by the app.url value from your october.yaml file\n```\n\nThere is a special placeholder `%app.hostname%` available that will be replaced by the host part\nof your `app.url`:\n\n```ini\n%app.url%      = http://october.dev\n%app.hostname% = october.dev\n``` \n\n#### File templates from a git repository\n\nIf your templates folder is a git repository `oc-bootstrapper` will pull the latest changes for the repo every time \nyou run `october init`.\n\nThis is a great feature if you want to share the template files with your team via a central \ngit repository. Just make sure you are able to fetch the latest changes via `git pull` and you're all set!\n\n```bash\ncd ~/.config/composer/october\ngit clone your-central-templates-repo.git .\ngit branch --set-upstream-to=origin/master master\ngit pull # Make sure this works without any user interaction\n```\n\n\n### Development environments\n\n`oc-bootstrapper` can set up a development environment for you. Currently, only [Lando](https://lando.dev/) is supported\nout of the box.\n\nTo enable the Lando integration, run `october init` and select `lando` as a dev environment. A `.lando.yml` file will be placed in your project. \n \nYou can now simply run `lando start` to get everything up and running inside a Docker environment created by Lando.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffline-gmbh%2Foc-bootstrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foffline-gmbh%2Foc-bootstrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffline-gmbh%2Foc-bootstrapper/lists"}