Repository files navigation

Rancherize is a php cli script based on symfony/console. It makes developing with docker and rancher easy for developerswithout specialized knowledge in the subjects.This is done by choosing a blueprint that fits your apps required environment and setting abstract requirements insteadof of adding and connecting services.

For a concrete example on how the configuration becomes easier through this see the example at the bottom of this page.

As of 2.23.0 the default behaviour for pushed services has changed to always pull images on an upgrade.
This can be disabled by settingdocker.always-pull: false in either the defaults or the environment.

Rancherize comes bundled as Docker Containeripunktbs/rancherize.

Rancherize creates configuration to be used with external docker tools. Thus it is necessary to have the following toolsinstalled to use Rancherize:

• dockerhttps://docs.docker.com/engine/installation/

No need to separately install it. To use it, just make a shell alias:

alias rancherize='docker run -it --init -v $HOME/.rancherize:/home/rancherize/.rancherize -v /var/run/docker.sock:/var/run/docker.sock -v $(pwd):$(pwd) -w $(pwd) -e "USER_ID=$(id -u)" -e "GROUP_ID=$(id -g)" ipunktbs/rancherize:2-stable'

or use the provided scriptscript/rancherize.sh.

From now on use rancherize without other dependencies for your local environment than docker.

With build tools like jenkins or gitlab-ci, you cannot rely on the presence of a .rancherize file in the home-dir. For this usecase you can set account settings with environment variables on thedocker container on runtime. best practise would be to include these variables via secrets.

• DOCKER_SERVER - registry server (e.g. registry.gitlab.com), ignore or leave empty for dockerhub
• DOCKER_USER - username for dockerhub / registry
• DOCKER_PASSWORD - password for dockerhub / registry
• DOCKER_ECR - true if usingAWS ECR
• RANCHER_URL - rancher environment api-url
• RANCHER_KEY - rancher api-key
• RANCHER_SECRET - rancher api-secret
• RANCHER_ACCOUNTNAME_URL - alternative rancher environment api-url when using rancher.account = 'ACCOUNTNAME'
• RANCHER_ACCOUNTNAME_KEY - alternative rancher api-key when using rancher.account = 'ACCOUNTNAME'
• RANCHER_ACCOUNTNAME_SECRET - alternative rancher api-secret when using rancher.account = 'ACCOUNTNAME'

Note thatRANCHER_ACCOUNTNAME_{URL,KEY,SECRET} are only parsed whenRANCHER_URL is set. Setting them without defaultaccount will NOT work.

Rancherize creates configuration to be used with external docker tools. Thus it is necessary to have the following toolsinstalled to use Rancherize:

• dockerhttps://docs.docker.com/engine/installation/
• docker-composehttps://docs.docker.com/compose/install/
• rancher-composehttps://docs.rancher.com/rancher/v1.2/en/cattle/rancher-compose/#installation

Rancherize is installed using composer

composer require 'ipunkt/rancherize:^2.5.0'

Rancherize knows 2 types of accounts:

• docker accounts. They are used to push images to docker hub
• rancher accounts. They are used to deploy your app to your rancher environment

Both are managed in the json file~/.rancherize which should be set to be only readable by your own user.
For easy editing use the following command. It opens the file in your$EDITOR and creates a default fileif it does not exist yet.

vendor/bin/rancherize rancher:access

Rancherize configuration is split intoenvironments. A typical app knows at least alocal and aproductionenvironment. Environments are configured by editing the filerancherize.json inside the app work directory.

Note that all configuration values can also be set in thedefaults section. Values in this section will be used if theconfiguration value does not appear in theenvironmentSeeEnvironments and Defaults for a longer explanation on how to best use environments

The commandinit can be used to create an initial configuration for an environment.
It will prompt the blueprint to create a sensible default production configuration. If the--dev Flag is used thena configuration for a local development environment is created instead.

vendor/bin/rancherize init [--dev] BLUEPRINT ENVIRONENTNAME1 ENVIRONEMNTNAME2... ENVIRONMENTNAMEXe.g.vendor/bin/rancherize init --dev webserver localvendor/bin/rancherize init webserver production staging

The commandenvironment:set exists to conveniently set an environment value for allenvironments. It will go throughallenvironments, display the current value and ask for the new value. If none is given then the old valuewill be used again.

vendor/bin/rancherize environment:set VARIABLENAMEe.g.vendor/bin/rancherize environment:set APP_KEY

The commandstart exists to start an environment of your app on the local machine.

vendor/bin/rancherize start ENVIRONMENTNAMEe.g.vendor/bin/rancherize start local

Note that this command does not currently build a docker image from your work directory so theenvironment should beset to mount your work directory directly. For the WebserverBlueprint this means setting

• "use-app-container": false
• "mount-workdir":"true"

Theses settings are included when initializing with the--dev flag

The commandpush exists to deploy the current state of your work directory into Rancher.

vendor/bin/rancherize push ENVIRONEMNT VERSIONe.g.vendor/bin/rancherize push staging v1

• The current state of your work directory is build as docker image and tagged as$(docker.repository):$(docker.version-prefix)VERSION
• The built Image is pushed to docker hub using the credentials from the global configuration named$(docker.account)
• The current configuration of the stack in rancher is retrieved
  • If the stack does not exist yet it is created empty
• The apps configuration is added to the stack configuration
• The app is deployed into the stack
  • If no other version of the service is found it will be created
  • !NEW! Ifrancher.in-service is set totrue then a rolling upgrade will be triggered to a non-versionized nameand subsequently in-service upgrades of this service
  • If the same version of the service is found then an in-service upgrade is triggered
  • If a different version of the service is found then a rolling-upgrade ist triggered
  • In case of an in-service upgrade rancherize waits for the stack to reachupgraded and confirms the upgrade.
    You can setrancher.upgrade-healthcheck totrue to wait for it to reporthealthy instead. Not that this onlyworks if a service has a health-check is defined(not yet supported through rancherize)

The commandbuild-image exists to build the current state of your work directory into the docker registry, then deploythem viapush -i.It is essentially thepush command without any interaction with rancher.

• Force resource limits

• Php Webserver
• Php Cli

See theBlueprint readme for more information on how to develop your own blueprints

List of examples