qobo / deploy
Deployment automation framework
Requires
- corneltek/getoptionkit: ~2
- qobo/pattern: ~1.0
- sensiolabs/ansi-to-html: ~1.1
- swiftmailer/swiftmailer: @stable
Requires (Dev)
- phpunit/phpunit: 4.3.*
This package is auto-updated.
Last update: 2023-04-08 19:34:22 UTC
README
Deploy is a deployment automation framework.
Assumptions
Here are things that help to make sense of this all:
- You are an automation freak!
- You need to deploy one or more projects on a regular basis.
- Each of your projects has one more environments (local, dev, QA, live, etc)
- Each of your environments has one or more locations (web servers, DB servers, etc)
- Each of your projects already has a build automation script (phing, phake, make, etc)
- You want to separate build automation from infrastructure configuration automation.
Install
Installing with composer is a breeze. Create a new folder:
$ mkdir my-deploys
$ cd my-deploys
Create composer.json
file with the following content:
{
"require": {
"qobo/deploy": "~1.0"
}
}
Now let composer do its magic:
$ composer install
You should see vendor
folder and have vendor/bin/deploy
available for
execution.
Now, create a folder for your configuration files. If you call it etc/
your
life will be much easier:
$ mkdir etc
Now you can run the deploy script to examine available parameters and such:
$ ./vendor/bin/deploy
It won't be much until you create some configuration files though. For a starting
point, use the sample provided in vendor/qobo/deploy/etc/some.project.com.jsom
For extra bonus, version your deployment configurations with git:
$ git init
$ echo "vendor/" > .gitignore
$ git add .
$ git commit -m "Initial commit"
If you push this to a remote repository, you'll have a backup too! :)
Usage
First, create at least one configuration file, like this one:
{
"type": "project",
"name": "Some Project",
"params": {
"base.dir": "/var/www/html/vhosts",
"project.dir": "test.qobo.biz",
"source.url": "git@github.com:QoboLtd/deploy.git",
"source.version": "master",
"source.install": "cd %%base.dir%% && git clone %%source.url%% %%project.dir%%",
"source.update": "cd %%base.dir%% && cd %%project.dir%% && git pull && %%source.checkout%%",
"source.checkout": "git checkout %%source.version%%",
"ssh.host": "localhost",
"ssh.user": "root",
"ssh.command": "ssh %%ssh.user%%@%%ssh.host%%"
},
"commands": {
"install": {
"type": "command",
"command": "%%ssh.command%% '%%source.install%% && cd %%project.dir%% && %%source.checkout%%'"
},
"update": {
"type": "command",
"command": "%%ssh.command%% '%%source.update%% && cd %%project.dir%% && %%source.version%%'"
},
"remove": {
"type": "command",
"command": "%%ssh.command%% 'cd %%base.dir%% && rm -rf %%project.%%dir%%'"
}
},
"environments": {
"live": {
"type": "environment",
"commands": {
"remove": {
"type": "command",
"command": ""
}
},
"locations": {
"web1": {
"type": "location",
"params": {
"ssh.host": "some-web-host1",
"base.dir": "/var/www/html"
}
},
"web2": {
"type": "location",
"params": {
"source.version": "stable",
"ssh.host": "some-web-host2",
"base.dir": "/usr/share/www"
}
}
}
}
}
}
Now you are ready to deploy. Have a look at the available projects:
$ ./vendor/bin/deploy list
Examine deployment targets from a specific project:
$ ./vendor/bin/deploy show --project some.domain.com
See what is going to be executed (--test)
$ ./vendor/bin/deploy run --test --project some.domain.com --env live --command install
Running deploy script without parameters or with an invalid set of parameters will print out a helpful (hopefully) message. Both short and long parameters are suppored.
Configuration
Configuration files only seem complicated. But they aren't. Here is some more info.
Types
Each section has a type, such as project, environment, location, or command. This is pretty much the only requirement. Current logic follows the assumptions listed above. But you can easily modify that, if you are prepared to tweak some PHP code (lib/Deploy/Runnable/ folder is for you).
Propagation
Deploy settings are propagated from top to bottom. That is, project settings are used as defaults for environments. Environments should only override what is different. Environment settings are used as defaults for locations, which can again redefine things on their own level. Location settings are passed to the command sections, which can have their last word.
You can have as many settings or sections as you need - everything is propagated downwards. However, you should probably avoid putting too much trust into fields 'name' and 'type', as they are used internall. For now. ;)
Params
Params is a special section. It can be used to pass parameters to your commands. Or, in fact, redesign your commands completely. The format is simple - keys and values. However, the parsing is recursive, so you can have really powerful and deeply nested templates.
Keep in mind PHP's default recursion level limit though, which is around 100 by default.
Commands
Commands define the things that will be executed during deployment. To make things easier automateable, commands are done with aliases. You should use generic names like 'install', 'update', 'remove', 'test', 'backup', etc. And then, within the command itself, do what is needed. This allows for very flexible configuration between different environments (live/dev/test) and multiple locations (say web servers with different operating systems).
Warning
Don't assume this whole thing works perfectly every time! It might change you life to the better or it might destroy you and eat your data and soul. Be warned.