├── images └── laravel.png ├── usage-on-windows.md ├── servers.md ├── functions.md ├── README.md ├── advanced ├── parallel-io.md ├── deploy-and-git.md └── deploy-strategies.md ├── examples └── inventory.md ├── installation.md ├── how-to-deploy-laravel.md ├── cli.md ├── getting-started.md ├── flow.md ├── hosts.md ├── api.md ├── configuration.md └── tasks.md /images/laravel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/deployphp/docs/HEAD/images/laravel.png -------------------------------------------------------------------------------- /usage-on-windows.md: -------------------------------------------------------------------------------- 1 | TODO 2 | 3 | * https://msdn.microsoft.com/en-us/commandline/wsl/about 4 | -------------------------------------------------------------------------------- /servers.md: -------------------------------------------------------------------------------- 1 | # Servers 2 | 3 | Servers was renamed to [hosts](hosts.md) in Deployer 5.x. 4 | If you are looking for documentation to Deployer 4.x follow [this link](https://github.com/deployphp/docs/tree/4.x). 5 | -------------------------------------------------------------------------------- /functions.md: -------------------------------------------------------------------------------- 1 | # Functions 2 | 3 | Documentation about available function moved to [API Reference](api.md). 4 | 5 | > If you are looking for documentation to Deployer 4.x follow [this link](https://github.com/deployphp/docs/tree/4.x). -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | > 2 | > # This is documentation for v6.x version 3 | > ### Documentation for v7.x migrated into [deployer repository](https://github.com/deployphp/deployer/tree/master/docs) 4 | > 5 | 6 | # Documentation 7 | 8 | ## Main Concepts 9 | 10 | * [Getting started](getting-started.md) 11 | * [Installation](installation.md) 12 | * [Configuration](configuration.md) 13 | * [Tasks](tasks.md) 14 | * [Hosts](hosts.md) 15 | * [Flow](flow.md) 16 | * [CLI Usage](cli.md) 17 | * [API Reference](api.md) 18 | 19 | ## Advanced 20 | 21 | * [Strategy](advanced/deploy-strategies.md) 22 | * [Deploy and Git](advanced/deploy-and-git.md) 23 | * [Parallel IO](advanced/parallel-io.md) 24 | 25 | ## How To 26 | 27 | * [How to deploy Laravel](how-to-deploy-laravel.md) 28 | 29 | ## Examples 30 | 31 | * [Inventory](examples/inventory.md) 32 | -------------------------------------------------------------------------------- /advanced/parallel-io.md: -------------------------------------------------------------------------------- 1 | # Dealing with IO in parallel mode 2 | 3 | If you try to make a task which will be asking a user, for example about a branch, 4 | but you still want to use parallel deploy, you may notice that it's now working and the program doesn't wait for user input. 5 | 6 | To workaround this problem, you need to create a local task and ask the user about the branch there: 7 | 8 | ~~~php 9 | task('what_branch', function () { 10 | $branch = ask('What branch to deploy?'); 11 | 12 | on(roles('app'), function ($host) use ($branch) { 13 | set('branch', $branch); 14 | }); 15 | })->local(); 16 | ~~~ 17 | 18 | And call this task before the `deploy` task: 19 | 20 | ~~~php 21 | before('deploy', 'what_branch'); 22 | ~~~ 23 | 24 | Now it should work as expected and the user will be asked for the branch only once. 25 | 26 | ~~~sh 27 | $ dep deploy -p 28 | ➤ Executing task what_branch 29 | What branch to deploy? master 30 | ✔ Ok 31 | ✔ Executing task deploy:prepare 32 | ✔ Executing task deploy:release 33 | ... 34 | ~~~ 35 | -------------------------------------------------------------------------------- /examples/inventory.md: -------------------------------------------------------------------------------- 1 | # Inventory Examples 2 | 3 | You can choose any inventory management you want or use one of next examples. 4 | 5 | ### One or two hosts 6 | 7 | In most scenarios your project will have one or two hosts: one for production and one for staging. 8 | So there is no need to separate inventory file, you can write everything in single _deploy.php_ file. 9 | 10 | For single host you don't need anything. Deployer will deploy to all defined hosts if no _stage_ parameter specified. 11 | 12 | ```php 13 | set('deploy_path', '~/project'); 14 | 15 | host('project.com'); 16 | ``` 17 | 18 | If you have one host for production and another for staging the next example is sufficient. 19 | 20 | > Right behavior for `dep deploy` command is to _deploy staging_, and to deploy prod is `dep deploy production`. 21 | 22 | ```php 23 | set('application', 'project'); 24 | set('deploy_path', '~/{{application}}'); 25 | set('default_stage', 'staging'); 26 | 27 | host('project.com') 28 | ->stage('production'); 29 | 30 | host('staging.project.com') 31 | ->stage('staging'); 32 | ``` 33 | 34 | > **Best practice** is to leave connecting information for hosts in the `~/.ssh/config` file. 35 | > That way you allow different users to connect in different ways. 36 | 37 | ### Separate inventory files 38 | 39 | TODO 40 | -------------------------------------------------------------------------------- /advanced/deploy-and-git.md: -------------------------------------------------------------------------------- 1 | # Deploy and Git 2 | 3 | To clone your repository you need to access your git server. 4 | Check if you have access from your server to github with this command: 5 | 6 | ~~~bash 7 | ssh git@github.com 8 | ~~~ 9 | 10 | 11 | There are two possibilities: deploy keys and agent forwarding. 12 | 13 | ## Deploy keys 14 | 15 | A deploy key is a SSH key set in your repo to grant client read-only access to your repo. 16 | As the name says, its primary function is to be used in the deploy process, where only read access is needed. 17 | Anyone with access to the repository and server will have the ability to deploy the project. 18 | 19 | * [Generate a ssh key](https://help.github.com/articles/connecting-to-github-with-ssh/) 20 | * Add the ssh key to the repository's deploy keys setting 21 | 22 | > Make sure your repo url uses git protocol not https, which means use `git@github.com:user/repo.git` 23 | 24 | 25 | ## Agent forwarding 26 | 27 | In many cases, especially at the beginning of a project, 28 | SSH agent forwarding is the quickest and simplest method to use. 29 | Agent forwarding uses the same SSH keys that your local development computer uses. 30 | 31 | **Pros** 32 | * You do not have to generate or keep track of any new keys. 33 | * There is no key management; users have the same permissions on the server that they do locally. 34 | 35 | **Cons** 36 | * Automated deploy processes can't be used. 37 | 38 | By default, Deployer uses agent forwarding: 39 | 40 | ~~~php 41 | host(...) 42 | ->forwardAgent() 43 | ~~~ 44 | -------------------------------------------------------------------------------- /installation.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | There are three ways to install deployer: 4 | 5 | 1. download phar archive 6 | 2. source composer installation 7 | 3. distribution composer installation 8 | 9 | ### Download phar archive 10 | 11 | To install Deployer as phar archive, run the following commands: 12 | 13 | ```sh 14 | curl -LO https://deployer.org/deployer.phar 15 | mv deployer.phar /usr/local/bin/dep 16 | chmod +x /usr/local/bin/dep 17 | ``` 18 | 19 | If you need another version of Deployer, you can find it on the [download page](https://deployer.org/download). 20 | Later, to upgrade Deployer, run the command: 21 | 22 | ```sh 23 | dep self-update 24 | ``` 25 | 26 | To upgrade to the next major release, if available, use the `--upgrade (-u)` option: 27 | 28 | ```sh 29 | dep self-update --upgrade 30 | ``` 31 | 32 | ### Source composer installation 33 | 34 | To install Deployer source version with Composer, run the command: 35 | 36 | ```sh 37 | composer require deployer/deployer --dev 38 | ``` 39 | 40 | You can also install it globally: 41 | 42 | ``` sh 43 | composer global require deployer/deployer 44 | ``` 45 | 46 | More info: https://getcomposer.org/doc/03-cli.md#global 47 | 48 | Then to use Deployer, run the following command: 49 | 50 | ```sh 51 | php vendor/bin/dep 52 | ``` 53 | 54 | > If you have installed Deployer using **both** methods, running `dep` command will prefer a composer-installed version. 55 | 56 | > If you have dependency conflicts you can use "distribution composer installation" 57 | 58 | ### Distribution composer installation 59 | 60 | To install Deployer distribution version with Composer, run the command: 61 | 62 | ```sh 63 | composer require deployer/dist --dev 64 | ``` 65 | 66 | Then to use Deployer, run the following command: 67 | 68 | ```sh 69 | php vendor/bin/dep 70 | ``` 71 | 72 | ### Own builded phar 73 | 74 | If you want to build Deployer from the source code, clone the project from GitHub: 75 | 76 | ```sh 77 | git clone https://github.com/deployphp/deployer.git 78 | ``` 79 | 80 | Then run the following command in the project directory: 81 | 82 | ```sh 83 | php bin/build 84 | ``` 85 | 86 | This will build the `deployer.phar` phar archive. 87 | 88 | 89 | ### Autocomplete 90 | 91 | Deployer comes with an autocomplete script for bash/zsh/fish, so you don't need to remember all tasks and options. 92 | To install, run the following command: 93 | 94 | ~~~bash 95 | dep autocomplete 96 | ~~~ 97 | 98 | And follow the instructions. 99 | 100 | Read [getting started](getting-started.md) next. 101 | -------------------------------------------------------------------------------- /how-to-deploy-laravel.md: -------------------------------------------------------------------------------- 1 | # How to deploy Laravel 2 | 3 | Apparently you already have some **Laravel application** and some **server** or **shared hosting**. 4 | Now you need to automate the process of **deployment**. 5 | Deployer will helps you in this as it ships with some ready to use recipes for **Laravel** based application. 6 | 7 | Let's start with [installation](installation.md) of Deployer. Run next commands in terminal: 8 | 9 | ```sh 10 | curl -LO https://deployer.org/deployer.phar 11 | mv deployer.phar /usr/local/bin/dep 12 | chmod +x /usr/local/bin/dep 13 | ``` 14 | 15 | Next, in your projects directory run: 16 | 17 | ```sh 18 | dep init -t Laravel 19 | ``` 20 | 21 | Command will create `deploy.php` file for *deploying Laravel*. This file called *recipe* and based on built-in recipe *laravel.php*. 22 | It's contains some host configuration and example task. 23 | 24 | First, we need to configure `repository` config of our application: 25 | 26 | ```php 27 | set('repository', 'git@github.com:user/project.git'); 28 | ``` 29 | 30 | Second, configure host: 31 | 32 | ```php 33 | host('domain.org') 34 | ->set('deploy_path', '/var/www/html'); 35 | ``` 36 | 37 | Make sure what `~/.ssh/config` contains `domain.org` and you can connect to host using ssh. 38 | 39 | Another important parameter it is `deploy_path`, where you project will be located on remote host. 40 | 41 | Let's do our first deploy: 42 | 43 | ```sh 44 | dep deploy 45 | ``` 46 | 47 | If every think goes well, deployer will create next structure on remote host in `deploy_path`: 48 | 49 | ```text 50 | ├── .dep 51 | ├── current -> releases/1 52 | ├── releases 53 | │   └── 1 54 | └── shared 55 | ├── .env 56 | └── storage 57 | ``` 58 | 59 | * `releases` dir contains *deploy* releases of *Laravel* application, 60 | * `shared` dir contains `.env` config and `storage` which will be symlinked to each release, 61 | * `current` is symlink to last release, 62 | * `.dep` dir contains special metadata for deployer (releases log, `deploy.log` file, etc). 63 | 64 | Configure you server to serve files from `current`. For example if you are using nginx next: 65 | 66 | ```config 67 | server { 68 | listen 80; 69 | server_name domain.org; 70 | 71 | root /var/www/html/current/public; 72 | 73 | location / { 74 | try_files $uri /index.php$is_args$args; 75 | } 76 | } 77 | ``` 78 | 79 | Now you will be able to serve you **laravel project**: 80 | 81 | ![Laravel App](images/laravel.png) 82 | 83 | If you want to automatically migrate database, *Laravel* recipe ships with `artisan:migrate` task. Add this lines to your `deploy.php`: 84 | 85 | ```php 86 | after('deploy:update_code', 'artisan:migrate'); 87 | ``` 88 | 89 | More about configuration and task declarations in our [documentation](getting-started.md). 90 | 91 | ... 92 | -------------------------------------------------------------------------------- /advanced/deploy-strategies.md: -------------------------------------------------------------------------------- 1 | # Deploy strategies 2 | 3 | ### Single server 4 | 5 | In most cases you don't need more than one production server. 6 | It's better to build your release files (as cache, js/css bundles) on that machine as well. 7 | So your builds don't depend on your local configuration and can be deployed from everywhere. 8 | By default Deployer recipes are designed to fullfill these kind of deployments. 9 | 10 | ~~~php 11 | desc('Deploy your project'); 12 | task('deploy', [ 13 | 'deploy:prepare', 14 | 'deploy:release', 15 | 'deploy:update_code', 16 | 'deploy:shared', 17 | 'deploy:vendors', 18 | 'deploy:symlink', 19 | ]); 20 | ~~~ 21 | 22 | ### Build server 23 | 24 | If you have a lot of servers where are you going to deploy your application, or you are going to use a CI server, 25 | it's better to build your release on one server and then upload files to the application servers. 26 | 27 | To do that create a _build_ local task: 28 | 29 | ~~~php 30 | task('build', function () { 31 | run('composer install'); 32 | run('npm install'); 33 | run('npm run build'); 34 | // ... 35 | })->local(); 36 | ~~~ 37 | 38 | > Note, you can use a simple task definition too 39 | > ~~~php 40 | > task('build', ' 41 | > composer install 42 | > npm install 43 | > npm run build 44 | > ... 45 | > '); 46 | > ~~~ 47 | 48 | After create an _upload_ task: 49 | 50 | ~~~php 51 | task('upload', function () { 52 | upload(__DIR__ . "/", '{{release_path}}'); 53 | }); 54 | ~~~ 55 | 56 | 57 | Next, create release and deploy tasks: 58 | 59 | ~~~php 60 | task('release', [ 61 | 'deploy:prepare', 62 | 'deploy:release', 63 | 'upload', 64 | 'deploy:shared', 65 | 'deploy:writable', 66 | 'deploy:symlink', 67 | ]); 68 | 69 | task('deploy', [ 70 | 'build', 71 | 'release', 72 | 'cleanup', 73 | 'success' 74 | ]); 75 | ~~~ 76 | 77 | Now you can run the `dep deploy` command. 78 | 79 | ### Reuse common recipe 80 | 81 | If you want to reuse some tasks from the common recipe, make sure that you set the `deploy_path` before invoking tasks. 82 | All common recipe tasks rely on this parameter. 83 | 84 | ~~~php 85 | task('build', function () { 86 | set('deploy_path', __DIR__ . '/.build'); 87 | invoke('deploy:prepare'); 88 | invoke('deploy:release'); 89 | invoke('deploy:update_code'); 90 | invoke('deploy:vendors'); 91 | // Add more build steps here 92 | invoke('deploy:symlink'); 93 | })->local(); 94 | ~~~ 95 | 96 | > Make sure that you set `deploy_path` before invoking tasks. 97 | 98 | After create an upload task: 99 | 100 | ~~~php 101 | task('upload', function () { 102 | upload(__DIR__ . "/.build/current/", '{{release_path}}'); 103 | }); 104 | ~~~ 105 | 106 | This task takes content from the current symlink of `deploy_path` from the build step and then uploads it to the application `release_path` path. 107 | -------------------------------------------------------------------------------- /cli.md: -------------------------------------------------------------------------------- 1 | # CLI Usage 2 | 3 | After [installation](installation.md) of Deployer you will have the ability to run the `dep` command from your terminal. 4 | 5 | To get list of all available tasks run the `dep` command. You can run it from any subdirectories of you project; 6 | Deployer will automatically find project root dir. 7 | 8 | ~~~bash 9 | Deployer 10 | 11 | Usage: 12 | command [options] [arguments] 13 | 14 | Options: 15 | -h, --help Display this help message 16 | -q, --quiet Do not output any message 17 | -V, --version Display this application version 18 | --ansi Force ANSI output 19 | --no-ansi Disable ANSI output 20 | -n, --no-interaction Do not ask any interactive question 21 | -f, --file[=FILE] Specify Deployer file 22 | -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug 23 | 24 | Available commands: 25 | help Displays help for a command 26 | init Initialize deployer system in your project 27 | list Lists commands 28 | run Run any arbitrary command on hosts 29 | self-update Updates deployer.phar to the latest version 30 | ssh Connect to host through ssh 31 | ~~~ 32 | 33 | The best way to configure your `deploy.php` is to automatically deploy to staging on this command: 34 | 35 | ~~~bash 36 | dep deploy 37 | ~~~ 38 | 39 | This is so somebody can't accidentally deploy to production (for production deployment, the `dep deploy production` command explicitly lists the required production stage). 40 | 41 | You need info about available options and usage use the `help` command: 42 | 43 | ~~~bash 44 | $ dep help deploy 45 | Usage: 46 | deploy [options] [--] [] 47 | 48 | Arguments: 49 | stage Stage or hostname 50 | 51 | Options: 52 | -p, --parallel Run tasks in parallel 53 | -l, --limit=LIMIT How many host to run in parallel? 54 | --no-hooks Run task without after/before hooks 55 | --log=LOG Log to file 56 | --roles=ROLES Roles to deploy 57 | --hosts=HOSTS Host to deploy, comma separated, supports ranges [:] 58 | -o, --option=OPTION Sets configuration option (multiple values allowed) 59 | -h, --help Display this help message 60 | -q, --quiet Do not output any message 61 | -V, --version Display this application version 62 | --ansi Force ANSI output 63 | --no-ansi Disable ANSI output 64 | -n, --no-interaction Do not ask any interactive question 65 | -f, --file[=FILE] Specify Deployer file 66 | --tag[=TAG] Tag to deploy 67 | --revision[=REVISION] Revision to deploy 68 | --branch[=BRANCH] Branch to deploy 69 | -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug 70 | 71 | Help: 72 | Deploy your project 73 | ~~~ 74 | 75 | ### Overriding configuration options 76 | 77 | For example, if your _deploy.php_ file contains this configuration: 78 | 79 | ~~~php 80 | set('ssh_multiplexing', false); 81 | ~~~ 82 | 83 | And you want to enable [ssh multiplexing](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) without modifying the file, you can pass the `-o` option to the `dep` command: 84 | 85 | ~~~bash 86 | dep deploy -o ssh_multiplexing=true 87 | ~~~ 88 | 89 | To override multiple config options, you can pass multiple `-o` args: 90 | 91 | ~~~bash 92 | dep deploy -o ssh_multiplexing=true -o branch=master 93 | ~~~ 94 | 95 | ### Running arbitrary commands 96 | 97 | Deployer comes with a command to run any valid command on you server without modifying _deploy.php_ 98 | 99 | ~~~bash 100 | dep run 'ls -la' 101 | ~~~ 102 | 103 | To specify the hosts this command has the corresponding options: 104 | 105 | ~~~ 106 | --stage=STAGE Stage to deploy 107 | --roles=ROLES Roles to deploy 108 | --hosts=HOSTS Host to deploy, comma separated, supports ranges [:] 109 | ~~~ 110 | 111 | ### Getting help 112 | 113 | You can get more info about any commands by using the help command: 114 | 115 | ~~~ 116 | dep help [command] 117 | ~~~ 118 | 119 | ### Autocomplete 120 | 121 | Deployer comes with an autocomplete script for bash/zsh/fish, so you don't need to remember all the tasks and options. 122 | To install it run following command: 123 | 124 | ~~~bash 125 | dep autocomplete 126 | ~~~ 127 | 128 | And follow instructions. 129 | -------------------------------------------------------------------------------- /getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | First, let's [install Deployer](installation.md). Run the following commands in the terminal: 4 | 5 | ```sh 6 | curl -LO https://deployer.org/deployer.phar 7 | mv deployer.phar /usr/local/bin/dep 8 | chmod +x /usr/local/bin/dep 9 | ``` 10 | 11 | Now you can use Deployer via the `dep` command. 12 | Open up a terminal in your project directory and run: 13 | 14 | ```sh 15 | dep init 16 | ``` 17 | 18 | This command will create the `deploy.php` file in the current directory. It is called a *recipe* and contains configuration and tasks for deployment. 19 | By default all recipes extend the [common](https://github.com/deployphp/deployer/blob/master/recipe/common.php) recipe. Place your _deploy.php_ file in root of your project and type `dep` or `dep list` command. You will see a list of all available tasks. 20 | 21 | > You can call `dep` command in any subdirectory of your project. 22 | 23 | Defining your task is really simple: 24 | 25 | ```php 26 | task('test', function () { 27 | writeln('Hello world'); 28 | }); 29 | ``` 30 | 31 | To run that task, run: 32 | 33 | ```sh 34 | dep test 35 | ``` 36 | 37 | The output will be: 38 | 39 | ```text 40 | ➤ Executing task test 41 | Hello world 42 | ✔ Ok 43 | ``` 44 | 45 | Now let's create a task which will run commands on a remote host. For that we must configure deployer. 46 | Your newly created `deploy.php` file should contain a `host` declaration like this: 47 | 48 | ```php 49 | host('domain.com') 50 | ->stage('production') 51 | ->set('deploy_path', '/var/www/domain.com'); 52 | ``` 53 | 54 | > Also it's possible to declare hosts in a separate yaml file. Find out more about the [inventory](hosts.md#inventory-file). 55 | 56 | You can find out more about host configurations [here](hosts.md). Now let's define a task which will output a 57 | `pwd` command from the remote host: 58 | 59 | ```php 60 | task('pwd', function () { 61 | $result = run('pwd'); 62 | writeln("Current dir: $result"); 63 | }); 64 | ``` 65 | 66 | Run `dep pwd`, and you will get this: 67 | 68 | ```text 69 | ➤ Executing task pwd 70 | Current dir: /var/www/domain.com 71 | ✔ Ok 72 | ``` 73 | 74 | Now let's prepare for our first deploy. You need to configure parameters such as `repository`, `shared_files,` and others: 75 | 76 | ```php 77 | set('repository', 'git@domain.com:username/repository.git'); 78 | set('shared_files', [...]); 79 | ``` 80 | 81 | You can return the parameter values in each task using the `get` function. 82 | Also you can override each configuration for each host: 83 | 84 | ```php 85 | host('domain.com') 86 | ... 87 | ->set('shared_files', [...]); 88 | ``` 89 | 90 | Read more about [configuring](configuration.md) deploy. 91 | 92 | 93 | Now let's deploy our application: 94 | 95 | ```sh 96 | dep deploy 97 | ``` 98 | 99 | To include extra details in the output, you can increase verbosity with the `--verbose` option: 100 | 101 | * `-v` for normal output, 102 | * `-vv` for more verbose output, 103 | * `-vvv` for debug. 104 | 105 | Deployer will create the following directories on the host: 106 | 107 | * `releases` contains releases dirs, 108 | * `shared` contains shared files and dirs, 109 | * `current` symlink to current release. 110 | 111 | Configure your hosts to serve your public directory from `current`. 112 | 113 | > Note that deployer uses [ACL](https://en.wikipedia.org/wiki/Access_control_list) by default for setting up permissions. 114 | > You can change this behavior with `writable_mode` config. 115 | 116 | By default deployer keeps the last 5 releases, but you can increase this number by modifying the associated parameter: 117 | 118 | ```php 119 | set('keep_releases', 10); 120 | ``` 121 | 122 | If there is an error in the deployment process, or something is wrong with your new release, 123 | simply run the following command to rollback to the previous working release: 124 | 125 | ```sh 126 | dep rollback 127 | ``` 128 | 129 | You may want to run some task before/after other tasks. Configuring that is really simple! 130 | 131 | Let's reload php-fpm after `deploy` finishes: 132 | 133 | ```php 134 | task('reload:php-fpm', function () { 135 | run('sudo /usr/sbin/service php7-fpm reload'); 136 | }); 137 | 138 | after('deploy', 'reload:php-fpm'); 139 | ``` 140 | 141 | If you need to connect to the host, Deployer has a shortcut for faster access: 142 | 143 | ~~~sh 144 | dep ssh 145 | ~~~ 146 | 147 | This command will connect to selected hosts and cd to `current_path`. 148 | 149 | Read more about [configuring](configuration.md) deploy. 150 | -------------------------------------------------------------------------------- /flow.md: -------------------------------------------------------------------------------- 1 | # Flow 2 | 3 | If your recipe is based on the *common* recipe or one of the framework recipes shipped with Deployer, then you are using one of our default flows. 4 | Each flow is described as a group of other tasks in the `deploy` name space. A common deploy flow may look like this: 5 | 6 | ~~~php 7 | task('deploy', [ 8 | 'deploy:prepare', 9 | 'deploy:lock', 10 | 'deploy:release', 11 | 'deploy:update_code', 12 | 'deploy:shared', 13 | 'deploy:writable', 14 | 'deploy:vendors', 15 | 'deploy:clear_paths', 16 | 'deploy:symlink', 17 | 'deploy:unlock', 18 | 'cleanup', 19 | 'success' 20 | ]); 21 | ~~~ 22 | 23 | Framework recipes may differ in flow, but the basic structure is the same. You can create your own flow by overriding the `deploy` task, but a better solution is to use the cache. 24 | For example, if you want to run some task before you symlink the new release: 25 | 26 | ~~~php 27 | before('deploy:symlink', 'deploy:build'); 28 | ~~~ 29 | 30 | Or, to send notifications after a successful deployment: 31 | 32 | ~~~php 33 | after('success', 'notify'); 34 | ~~~ 35 | 36 | The next section provides a short overview of each task. 37 | 38 | ### deploy:prepare 39 | 40 | Preparation for deployment. Checks if `deploy_path` exists, otherwise create it. Also checks for the existence of the following paths: 41 | 42 | * `releases` – in this dir will be stored the releases. 43 | * `shared` – shared files across all releases. 44 | * `.dep` – metadata used by Deployer. 45 | 46 | ### deploy:lock 47 | 48 | Locks deployment so only one concurrent deployment can be running. To lock deployment, this task checks for the existence of the `.dep/deploy.lock` file. If the deploy process was cancelled by Ctrl+C, run `dep deploy:unlock` to delete this file. In the event that deployment fails, the `deploy:unlock` task will be triggered automatically. 49 | 50 | ### deploy:release 51 | 52 | Create a new release folder based on the `release_name` config parameter. Also reads `.dep/releases` to get a list of releases that were created before. 53 | 54 | Also, if in the `deploy_path` there was a previous release symlink, it will be deleted. 55 | 56 | ### deploy:update_code 57 | 58 | Download a new version of code using Git. If you are using Git version 2.0 and `git_cache` config is turned on, this task will use files from the previous release, so only changed files will be downloaded. 59 | 60 | Override this task in `deploy.php` to create your own code transfer strategy: 61 | 62 | ~~~php 63 | task('deploy:update_code', function () { 64 | upload('.', '{{release_path}}'); 65 | }); 66 | ~~~ 67 | 68 | ### deploy:shared 69 | 70 | Creates shared files and directories from the `shared` directory into the `release_path`. You can specify shared directories and files in `shared_dirs` and `shared_files` config parameters. The process is split into the following steps: 71 | 72 | * Copy dir from `release_path` to `shared` if doesn't exists, 73 | * delete dir from `release_path`, 74 | * symlink dir from `shared` to `release_path`. 75 | 76 | The same steps are followed for shared files. If your system supports relative symlinks then they will be used, otherwise absolute symlinks wil be used. 77 | 78 | ### deploy:writable 79 | 80 | Makes the directories listed in `writable_dirs` writable using `acl` mode (using setfacl command) by default. This task will try to guess http_user name, or you can configure it yourself: 81 | 82 | ~~~php 83 | set('http_user', 'www-data'); 84 | 85 | // Or only for specified host: 86 | host(...) 87 | ->set('http_user', 'www-data'); 88 | ~~~ 89 | 90 | Also this task supports other writable modes: 91 | 92 | * chown 93 | * chgrp 94 | * chmod 95 | * acl 96 | 97 | To use one of them add this: 98 | 99 | ~~~php 100 | set('writable_mode', 'chmod'); 101 | ~~~ 102 | 103 | To use sudo with writable add this: 104 | 105 | ~~~php 106 | set('writable_use_sudo', true); 107 | ~~~ 108 | 109 | ### deploy:vendors 110 | 111 | Install composer dependencies. You can configure composer options with the `composer_options` parameter. 112 | 113 | ### deploy:clear_paths 114 | 115 | Deletes dirs specified in `clear_paths`. This task can be run with sudo using the `clear_use_sudo` parameter. 116 | 117 | ### deploy:symlink 118 | 119 | Switch the `current` symlink to `release_path`. If target system supports atomic switching for symlinks it will used. 120 | 121 | ### deploy:unlock 122 | 123 | Deletes the `.dep/deploy.lock` file. You can run this task directly to delete the lock file: 124 | 125 | ~~~sh 126 | dep deploy:unlock staging 127 | ~~~ 128 | 129 | ### cleanup 130 | 131 | Clean up old releases using the `keep_releases` option. `-1` is treated as unlimited releases. 132 | 133 | ### success 134 | 135 | Prints a success message. 136 | -------------------------------------------------------------------------------- /hosts.md: -------------------------------------------------------------------------------- 1 | # Hosts 2 | 3 | Defining a host in Deployer is necessary to deploy your application. It can be a remote machine, a local machine or Amazon EC2 instances. 4 | Each host contains a hostname, a stage, one or more roles and configuration parameters. 5 | 6 | You can define hosts with the `host` function in `deploy.php` file. Here is an example of a host definition: 7 | 8 | ~~~php 9 | host('domain.com') 10 | ->stage('production') 11 | ->roles('app') 12 | ->set('deploy_path', '~/app'); 13 | ~~~ 14 | 15 | Host *domain.com* has stage `production`, one role `app` and a configuration parameter `deploy_path` = `~/app`. 16 | 17 | Hosts can also be described by using yaml syntax. Write this in a `hosts.yml` file: 18 | 19 | ~~~yaml 20 | domain.com: 21 | stage: production 22 | roles: app 23 | deploy_path: ~/app 24 | ~~~ 25 | 26 | Then to `deploy.php`: 27 | 28 | ~~~php 29 | inventory('hosts.yml'); 30 | ~~~ 31 | 32 | Make sure that your `~/.ssh/config` file contains information about your domains and how to connect. 33 | Or you can specify that information in the `deploy.php` file itself. 34 | 35 | ~~~php 36 | host('domain.com') 37 | ->user('name') 38 | ->port(22) 39 | ->configFile('~/.ssh/config') 40 | ->identityFile('~/.ssh/id_rsa') 41 | ->forwardAgent(true) 42 | ->multiplexing(true) 43 | ->addSshOption('UserKnownHostsFile', '/dev/null') 44 | ->addSshOption('StrictHostKeyChecking', 'no'); 45 | ~~~ 46 | 47 | > **Best practice** is to leave connecting information for hosts in the `~/.ssh/config` file. 48 | > That way you allow different users to connect in different ways. 49 | 50 | ### Overriding config per host 51 | 52 | For example, if you have some global configuration you can override it per host: 53 | 54 | ~~~php 55 | set('branch', 'master'); 56 | 57 | host('prod') 58 | ... 59 | ->set('branch', 'production'); 60 | ~~~ 61 | 62 | Now onthe _prod_ host the branch is set to `production`, on others to `master`. 63 | 64 | ### Gathering host info 65 | 66 | Inside any task, you can get host config with the `get` function, and the host object with the `host` function. 67 | 68 | ~~~php 69 | task('...', function () { 70 | $deployPath = get('deploy_path'); 71 | 72 | $host = host('domain.com'); 73 | $port = $host->getPort(); 74 | }); 75 | ~~~ 76 | 77 | ### Multiple hosts 78 | 79 | You can pass multiple hosts to the `host` function: 80 | 81 | ~~~php 82 | host('110.164.16.59', '110.164.16.34', '110.164.16.50', ...) 83 | ->stage('production') 84 | ... 85 | ~~~ 86 | 87 | If your inventory `hosts.yml` file contains multiple, you can change the config for all of them in the same way. 88 | 89 | ~~~php 90 | inventory('hosts.yml') 91 | ->roles('app') 92 | ... 93 | ~~~ 94 | 95 | ### Host ranges 96 | 97 | If you have a lot of hosts following similar patterns, you can describe them like this rather than listing each hostname: 98 | 99 | ~~~php 100 | host('www[01:50].domain.com'); 101 | ~~~ 102 | 103 | For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive. 104 | 105 | You can also define alphabetic ranges: 106 | 107 | ~~~php 108 | host('db[a:f].domain.com'); 109 | ~~~ 110 | 111 | ### Localhost 112 | 113 | If you need to build your release before deploying on a remote machine, or deploy to localhost instead of remote, 114 | you need to define localhost: 115 | 116 | ~~~php 117 | localhost() 118 | ->stage('production') 119 | ->roles('test', 'build') 120 | ... 121 | ~~~ 122 | 123 | ### Host aliases 124 | 125 | If you want to deploy an app to one host, but for example in different directories, you can describe two host aliases: 126 | 127 | ~~~php 128 | host('domain.com/green', 'domain.com/blue') 129 | ->set('deploy_path', '~/{{hostname}}') 130 | ... 131 | ~~~ 132 | 133 | For Deployer, those hosts are different ones, and after deploying to both hosts you will see this directory structure: 134 | 135 | ~~~ 136 | ~ 137 | └── domain.com 138 | ├── green 139 | │ └── ... 140 | └── blue 141 | └── ... 142 | ~~~ 143 | 144 | ### One host for a few stages 145 | 146 | Often you have only one server for prod and beta stages. You can easily configure them: 147 | 148 | ~~~php 149 | host('production') 150 | ->hostname('domain.com') 151 | ->set('deploy_path', '~/domain.com'); 152 | 153 | host('beta') 154 | ->hostname('domain.com') 155 | ->set('deploy_path', '~/beta.domain.com'); 156 | ~~~ 157 | 158 | Now you can deploy with these commands: 159 | 160 | ~~~sh 161 | dep deploy production 162 | dep deploy beta 163 | ~~~ 164 | 165 | ### Inventory file 166 | 167 | Include hosts defined in inventory files `hosts.yml` by `inventory` function: 168 | 169 | ~~~php 170 | inventory('hosts.yml'); 171 | ~~~ 172 | 173 | Here an example of an inventory file `hosts.yml` with the full set of configuration settings 174 | 175 | ~~~yaml 176 | domain.com: 177 | hostname: domain.com 178 | user: name 179 | port: 22 180 | configFile: ~/.ssh/config 181 | identityFile: ~/.ssh/id_rsa 182 | forwardAgent: true 183 | multiplexing: true 184 | sshOptions: 185 | UserKnownHostsFile: /dev/null 186 | StrictHostKeyChecking: no 187 | stage: production 188 | roles: 189 | - app 190 | - db 191 | deploy_path: ~/app 192 | extra_param: "foo {{hostname}}" 193 | ~~~ 194 | 195 | > **Note** that, as with the `host` function in the *deploy.php* file, it's better to omit information such as 196 | > *user*, *port*, *identityFile*, *forwardAgent* and use it from the `~/.ssh/config` file instead. 197 | 198 | If your inventory file contains many similar host definitions, you can use YAML extend syntax: 199 | 200 | ~~~yaml 201 | .base: &base 202 | roles: app 203 | deploy_path: ~/app 204 | ... 205 | 206 | www1.domain.com: 207 | <<: *base 208 | stage: production 209 | 210 | beta1.domain.com: 211 | <<: *base 212 | stage: beta 213 | 214 | ... 215 | ~~~ 216 | 217 | Hosts that start with `.` (*dot*) are called hidden and are not visible outside that file. 218 | 219 | To define localhost in inventory files add a `local` key: 220 | 221 | ~~~yaml 222 | localhost: 223 | local: true 224 | roles: build 225 | ... 226 | ~~~ 227 | 228 | ### Become 229 | 230 | Deployer allows you to ‘become’ another user, different from the user that logged into the machine (remote user). 231 | 232 | ~~~php 233 | host('domain.com') 234 | ->become('deployer') 235 | ... 236 | ~~~ 237 | 238 | Deployer uses `sudo` privilege escalation method by default. 239 | 240 | > **Note** that become doesn't work with `tty` run option. 241 | 242 | Next: [deployment flow](flow.md). 243 | -------------------------------------------------------------------------------- /api.md: -------------------------------------------------------------------------------- 1 | # API Reference 2 | 3 | ### host 4 | 5 | * `host(string ...$hostname): Host` 6 | 7 | Define a host or group of hosts. Read more at [hosts](hosts.md). 8 | 9 | ### localhost 10 | 11 | * `localhost(string ...$alias = 'localhost'): Host` 12 | 13 | Define a localhost. 14 | 15 | ### inventory 16 | 17 | * `inventory(string $file): Host[]` 18 | 19 | Load a list of hosts from a file. 20 | 21 | ### desc 22 | 23 | * `desc(string $description)` 24 | 25 | Set a task description. 26 | 27 | ### task 28 | 29 | * `task(string $name, string $script)` 30 | * `task(string $name, callable $callable)` 31 | * `task(string $name): Task` 32 | 33 | Define a task or get a task. More at [tasks](tasks.md). 34 | 35 | ### before 36 | 37 | * `before(string $when, string $that)` 38 | 39 | Call before `$when` task, `$that` task. 40 | 41 | ### after 42 | 43 | * `after(string $when, string $that)` 44 | 45 | Call after `$when` task, `$that` task. 46 | 47 | ### fail 48 | 49 | * `fail(string $what, string $that)` 50 | 51 | If task `$what` fails, run `$that` task. 52 | 53 | ### argument 54 | 55 | * `argument($name, $mode = null, $description = '', $default = null)` 56 | 57 | Add user's cli arguments. 58 | 59 | ### option 60 | 61 | * `option($name, $shortcut=null, $mode=null, $description='', $default=null)` 62 | 63 | Add user's cli options. 64 | 65 | ### cd 66 | 67 | * `cd(string $path)` 68 | 69 | Sets the working path for the following `run` functions. 70 | Every task restores the working path to the base working path at the beginning of the task. 71 | 72 | ~~~php 73 | cd('{{release_path}}'); 74 | run('npm run build'); 75 | ~~~ 76 | 77 | ### within 78 | 79 | * `within(string $path, callable $callback)` 80 | 81 | Run `$callback` within `$path`. 82 | 83 | ~~~php 84 | within('{{release_path}}', function () { 85 | run('npm run build'); 86 | }); 87 | ~~~ 88 | 89 | ### workingPath 90 | 91 | * `workingPath(): string` 92 | 93 | Return the current working path. 94 | 95 | ~~~php 96 | cd('{{release_path}}'); 97 | workingPath() == '/var/www/app/releases/1'; 98 | ~~~ 99 | 100 | ### run 101 | 102 | * `run(string $command, $options = []): string` 103 | 104 | Run a command on remote host. Available options: 105 | 106 | * `timeout` — Sets the process timeout (max. runtime). 107 | To disable the timeout, set this value to null. 108 | The timeout in seconds (default: 300 sec) 109 | * `tty` — Enables or disables the TTY mode (default: false) 110 | 111 | For example, if your private key contains a passphrase, enable tty and you'll see git prompt for a password. 112 | 113 | ~~~php 114 | run('git clone ...', ['timeout' => null, 'tty' => true]); 115 | ~~~ 116 | 117 | `run` function returns the output of the command as a string: 118 | 119 | ~~~php 120 | $path = run('readlink {{deploy_path}}/current'); 121 | run("echo $path"); 122 | ~~~ 123 | 124 | ### runLocally 125 | 126 | * `runLocally($command, $options = []): string` 127 | 128 | Run a command on localhost. Available options: 129 | 130 | * `timeout` — The timeout in seconds (default: 300 sec) 131 | * `tty` — The TTY mode (default: false) 132 | 133 | ### test 134 | 135 | * `test(string $command): bool` 136 | 137 | Run a test command. 138 | 139 | ~~~php 140 | if (test('[ -d {{release_path}} ]')) { 141 | ... 142 | } 143 | ~~~ 144 | 145 | ### testLocally 146 | 147 | * `testLocally(string $command): bool` 148 | 149 | Run a test command locally. 150 | 151 | ### on 152 | 153 | * `on(Host $host, callable $callback)` 154 | * `on(Host[] $host, callable $callback)` 155 | 156 | Execute a `$callback` on the specified hosts. 157 | 158 | ~~~php 159 | on(host('domain.com'), function ($host) { 160 | ... 161 | }); 162 | ~~~ 163 | 164 | ~~~php 165 | on(roles('app'), function ($host) { 166 | ... 167 | }); 168 | ~~~ 169 | 170 | ~~~php 171 | on(Deployer::get()->hosts, function ($host) { 172 | ... 173 | }); 174 | ~~~ 175 | 176 | ### roles 177 | 178 | * `roles(string ...$role): Host[]` 179 | 180 | Return a list of hosts by roles. 181 | 182 | ### invoke 183 | 184 | * `invoke(string $task)` 185 | 186 | Run a task on the current host. 187 | 188 | ~~~php 189 | task('deploy', function () { 190 | invoke('deploy:prepare'); 191 | invoke('deploy:release'); 192 | ... 193 | }); 194 | ~~~ 195 | 196 | > **Note** this is experimental functionality. 197 | 198 | ### upload 199 | 200 | * `upload(string $source, string $destination, $config = [])` 201 | 202 | Upload files from `$source` to `$destination` on the remote host. 203 | 204 | ~~~php 205 | upload('build/', '{{release_path}}/public'); 206 | ~~~ 207 | 208 | > You may have noticed that there is a trailing slash (/) at the end of the first argument in the above command, 209 | > this is necessary to mean "the contents of `build`". 210 | > 211 | > The alternative, without the trailing slash, would place `build`, including the directory, within `public`. 212 | > This would create a hierarchy that looks like: `{{release_path}}/public/build` 213 | 214 | Available options: 215 | 216 | * `timeout` — The timeout in seconds (default: null) 217 | * `options` — `rsync` options. 218 | 219 | ### download 220 | 221 | * `download(string $source, string $destination, $config = [])` 222 | 223 | Download files from the remote host `$source` to `$destination` on the local machine. 224 | 225 | Available options: 226 | 227 | * `timeout` — The timeout in seconds (default: null) 228 | * `options` — `rsync` options. 229 | 230 | ### write 231 | 232 | Write a message in the output. 233 | You can format the message with the tags `...`, `` or `` (see [Symfony Console](http://symfony.com/doc/current/console/coloring.html)). 234 | 235 | ### writeln 236 | 237 | Same as the `write` function, but also writes a new line. 238 | 239 | ### set 240 | 241 | * `set(string $name, string|int|bool|array $value)` 242 | * `set(string $name, callable $value)` 243 | 244 | Setup a global configuration parameter. If callable is passed as `$value` it will be triggered on the first get of this config. 245 | 246 | More at [configuration](configuration.md). 247 | 248 | ### add 249 | 250 | * `add(string $name, array $values)` 251 | 252 | Add values to already existing config. 253 | 254 | More at [configuration](configuration.md). 255 | 256 | ### get 257 | 258 | * `get(string $name, $default = null): string|int|bool|array` 259 | 260 | Get a configuration value. 261 | 262 | More at [configuration](configuration.md). 263 | 264 | ### has 265 | 266 | * `has(string $name): bool` 267 | 268 | Check if a config option exists. 269 | 270 | More at [configuration](configuration.md). 271 | 272 | ### ask 273 | 274 | * `ask(string $message, $default = null, $suggestedChoices = null)` 275 | 276 | Ask the user for input. 277 | 278 | ### askChoice 279 | 280 | * `askChoice(string $message, array $availableChoices, $default = null, $multiselect = false)` 281 | 282 | Ask the user to select from multiple key/value options and return an array. 283 | Multiselect enables selection of multiple comma separated choices. 284 | The default value will be used in quiet mode, otherwise the first available choice will be accepted. 285 | 286 | ### askConfirmation 287 | 288 | * `askConfirmation(string $message, bool $default = false)` 289 | 290 | Ask the user a yes or no question. 291 | 292 | ### askHiddenResponse 293 | 294 | * `askHiddenResponse(string $message)` 295 | 296 | Ask the user for a password. 297 | 298 | ### input 299 | 300 | * `input(): Input` 301 | 302 | Get the current console input. 303 | 304 | ### output 305 | 306 | * `output(): Output` 307 | 308 | Get the current console output. 309 | 310 | ### isQuiet 311 | 312 | * `isQuiet(): bool` 313 | 314 | Check if th `dep` command was started with the `-q` option. 315 | 316 | ### isVerbose 317 | 318 | * `isVerbose(): bool` 319 | 320 | Check if the `dep` command was started with the `-v` option. 321 | 322 | ### isVeryVerbose 323 | 324 | * `isVeryVerbose(): bool` 325 | 326 | Check if th `dep` command was started with the `-vv` option. 327 | 328 | ### isDebug 329 | 330 | * `isDebug(): bool` 331 | 332 | Check if the `dep` command was started with the `-vvv` option. 333 | 334 | 335 | ### commandExist 336 | 337 | * `commandExist(string $command): bool` 338 | 339 | Check if a command exists. 340 | 341 | ~~~php 342 | if (commandExist('composer')) { 343 | ... 344 | } 345 | ~~~ 346 | 347 | ### parse 348 | 349 | * `parse(string $line): string` 350 | 351 | Parse config occurrence `{{` `}}` in `$line`. 352 | -------------------------------------------------------------------------------- /configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | To setup a configuration parameter, use `set` function, and to get it inside task use `get` function. 4 | 5 | ~~~php 6 | set('param', 'value'); 7 | 8 | task('deploy', function () { 9 | $param = get('param'); 10 | }); 11 | ~~~ 12 | 13 | Each parameter can be overridden for each host: 14 | 15 | ~~~php 16 | host(...) 17 | ->set('param', 'new value'); 18 | ~~~ 19 | 20 | Configuration parameters also can be specified as callback function, which will be executed on remote host on first `get` call: 21 | 22 | ~~~php 23 | set('current_path', function () { 24 | return run('pwd'); 25 | }); 26 | ~~~ 27 | 28 | You can use a param's values inside `run` calls with `{{ }}`, instead of doing this: 29 | 30 | ~~~php 31 | run('cd ' . get('release_path') . ' && command'); 32 | ~~~ 33 | 34 | You can do this: 35 | 36 | ~~~php 37 | run('cd {{release_path}} && command'); 38 | ~~~ 39 | 40 | Common recipe comes with a few predefined config params listed below. 41 | 42 | To get list of available params run: 43 | 44 | ~~~sh 45 | dep config:dump 46 | ~~~ 47 | 48 | Show current deployed release: 49 | 50 | ~~~bash 51 | dep config:current 52 | ~~~ 53 | 54 | Show inventory: 55 | 56 | ~~~bash 57 | dep config:hosts 58 | ~~~ 59 | 60 | 61 | 62 | Below is a list of common variables. 63 | 64 | ### deploy\_path 65 | 66 | Where to deploy application on remote host. You should define this variable for all of your hosts. 67 | For example, if you want to deploy your app to home directory: 68 | 69 | ~~~php 70 | host(...) 71 | ->set('deploy_path', '~/project'); 72 | ~~~ 73 | 74 | ### hostname 75 | 76 | Current hostname. Automatically set by `host` function. 77 | 78 | ### user 79 | 80 | Current user name. Defaults to the current git user name: 81 | 82 | ~~~php 83 | set('user', function () { 84 | return runLocally('git config --get user.name'); 85 | }); 86 | ~~~ 87 | 88 | You can override it in _deploy.php_ for example to use env var: 89 | 90 | ~~~php 91 | set('user', function () { 92 | return getenv('DEP_USER'); 93 | }); 94 | ~~~ 95 | 96 | `user` parameter can be used to configure notification systems: 97 | 98 | ~~~php 99 | set('slack_text', '{{user}} deploying {{branch}} to {{hostname}}'); 100 | ~~~ 101 | 102 | ### release\_path 103 | 104 | Full path to the current release directory. Current dir path in non-deploy contexts. 105 | Use it as working path for your build: 106 | 107 | ~~~php 108 | task('build', function () { 109 | cd('{{release_path}}'); 110 | // ... 111 | }); 112 | ~~~ 113 | 114 | > By default, working path is `release_path` for simple task: 115 | > ~~~php 116 | > task('build', 'webpack -p'); 117 | > ~~~ 118 | 119 | ### previous\_release 120 | 121 | Points to previous release if it exists. Otherwise variable doesn't exist. 122 | 123 | ~~~php 124 | task('npm', function () { 125 | if (has('previous_release')) { 126 | run('cp -R {{previous_release}}/node_modules {{release_path}}/node_modules'); 127 | } 128 | 129 | run('cd {{release_path}} && npm install'); 130 | }); 131 | ~~~ 132 | 133 | ### ssh\_multiplexing 134 | 135 | Use [ssh multiplexing](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) to speedup the native ssh client. 136 | 137 | ~~~php 138 | set('ssh_multiplexing', true); 139 | ~~~ 140 | 141 | ### default\_stage 142 | 143 | If the hosts declaration has stages, this option allows you to select the default stage to deploy with `dep deploy`. 144 | 145 | ~~~php 146 | set('default_stage', 'prod'); 147 | 148 | host(...) 149 | ->stage('prod'); 150 | ~~~ 151 | 152 | You can also set callable as an argument if you need some more complex ways to determine default stage. 153 | 154 | Having callable in set() allows you to not set the value when declaring it, but later when it is used. There is no difference 155 | when we assign a simple string. But when we assign value of a function, then this function must be called at once, if not used 156 | as callable. With callable, it can be called when used, so a function which determines a variable can be overwritten by the user with its own function. This is the great power of having callable in set() instead of direct in function calls. 157 | 158 | **Example 1: Direct function assign in set()** 159 | 160 | Lets assume that we must include some third party recipe that is setting 'default_stage' like this: 161 | ~~~php 162 | set('default_stage', \ThirdPartyVendor\getDefaultStage()); 163 | ~~~ 164 | 165 | And we want to overwrite this in our deploy.php with our own value: 166 | ~~~php 167 | set('default_stage', \MyVendor\getDefaultStage()); 168 | ~~~ 169 | 170 | Third party recipe should avoid a direct function call, because it will be called always even if we overwrite it with 171 | our own set('default_stage', \MyVendor\getDefaultStage()). Look at the next example how the third party recipe should use 172 | callable in that case. 173 | 174 | **Example 2: Callable assign in set()** 175 | 176 | Lets assume that we must include some third party recipe that is setting 'default_stage' like this: 177 | ~~~php 178 | set('default_stage', function() { 179 | return \ThirdPartyVendor\getDefaultStage(); 180 | }); 181 | ~~~ 182 | 183 | And we want to overwrite this in our deploy.php: 184 | ~~~php 185 | set('default_stage', function() { 186 | return \MyVendor\getDefaultStage(); 187 | }); 188 | ~~~ 189 | 190 | The result is that only \MyVendor\getDefaultStage() is run. 191 | 192 | ### keep\_releases 193 | 194 | Number of releases to keep. `-1` for unlimited releases. Default to `5`. 195 | 196 | ### repository 197 | 198 | Git repository of the application. 199 | 200 | To use a private repository, you need to generate a SSH-key on your host and add it to the repository 201 | as a Deploy Key (a.k.a. Access Key). This key allows your host to pull out the code. Or use can use agent forwarding. 202 | 203 | Note that the first time a host connects, it can ask to add host in `known_hosts` file. The easiest way to do this is 204 | by running `git clone ` on your host and saying `yes` when prompted. 205 | 206 | ### git\_tty 207 | 208 | Allocate TTY for `git clone` command. `false` by default. This allow you to enter a passphrase for keys or add host to `known_hosts`. 209 | 210 | ~~~php 211 | set('git_tty', true); 212 | ~~~ 213 | 214 | ### git\_recursive 215 | 216 | Set the `--recursive` flag for git clone. `true` by default. Setting this to `false` will prevent submodules from being cloned as well. 217 | 218 | ~~~php 219 | set('git_recursive', false); 220 | ~~~ 221 | 222 | ### branch 223 | 224 | Branch to deploy. 225 | 226 | If you want to deploy a specific tag or a revision, you can use `--tag` and `--revision` options while running `dep deploy`. E.g. 227 | 228 | ~~~bash 229 | dep deploy --tag="v0.1" 230 | dep deploy --revision="5daefb59edbaa75" 231 | ~~~ 232 | 233 | Note that `tag` has higher priority than `branch` and lower than `revision`. 234 | 235 | ### shared\_dirs 236 | 237 | List of shared dirs. 238 | 239 | ~~~php 240 | set('shared_dirs', [ 241 | 'logs', 242 | 'var', 243 | ... 244 | ]); 245 | ~~~ 246 | 247 | ### shared\_files 248 | 249 | List of shared files. 250 | 251 | ### copy\_dirs 252 | 253 | List of files to copy between release. 254 | 255 | ### writable\_dirs 256 | 257 | List of dirs which must be writable for web server. 258 | 259 | ### writable\_mode 260 | 261 | Writable mode 262 | 263 | * `acl` (*default*) use `setfacl` for changing ACL of dirs. 264 | * `chmod` use unix `chmod` command, 265 | * `chown` use unix `chown` command, 266 | * `chgrp` use unix `chgrp` command, 267 | 268 | ### writable\_use\_sudo 269 | 270 | Whether to use `sudo` with writable command. Default to `false`. 271 | 272 | ### writable\_chmod\_mode 273 | 274 | Mode for setting `writable_mode` in `chmod`. Default: `0755`. 275 | 276 | ### writable\_chmod\_recursive 277 | 278 | Whether to set `chmod` on dirs recursively or not. Default: `true`. 279 | 280 | ### http\_user 281 | 282 | User the web server runs as. If this parameter is not configured, deployer try to detect it from the process list. 283 | 284 | ### clear\_paths 285 | 286 | List of paths which need to be deleted in release after updating code. 287 | 288 | ### clear\_use\_sudo 289 | 290 | Use or not `sudo` with clear\_paths. Default to `false`. 291 | 292 | ### cleanup\_use\_sudo 293 | 294 | Whether to use `sudo` with `cleanup` task. Default to `false`. 295 | 296 | ### use\_relative\_symlink 297 | 298 | Whether to use relative symlinks. By default deployer will detect if the system supports relative symlinks and use them. 299 | 300 | > Relative symlink used by default, if your system supports it. 301 | 302 | ### use\_atomic\_symlink 303 | 304 | Whether to use atomic symlinks. By default deployer will detect if system supports atomic symlinks and use them. 305 | 306 | > Atomic symlinking is used by default, if your system supports it. 307 | 308 | ### composer\_action 309 | 310 | Composer action. Default is `install`. 311 | 312 | ### composer\_options 313 | 314 | Options for Composer. 315 | 316 | ### env 317 | 318 | Array of environment variables. 319 | 320 | ~~~php 321 | set('env', [ 322 | 'VARIABLE' => 'value', 323 | ]); 324 | ~~~ 325 | 326 | 327 | Read more about [task definitions](tasks.md). 328 | -------------------------------------------------------------------------------- /tasks.md: -------------------------------------------------------------------------------- 1 | # Tasks 2 | 3 | Define your own tasks, by using the `task` function. Also, you can setup a description for a task with the `desc` function: 4 | 5 | ```php 6 | desc('My task'); 7 | task('my_task', function () { 8 | run(...); 9 | }); 10 | ``` 11 | 12 | To run your task: 13 | 14 | ```sh 15 | dep my_task 16 | ``` 17 | 18 | To list all available commands: 19 | 20 | ```sh 21 | dep list 22 | ``` 23 | 24 | To run a task only on a specified host or stage: 25 | 26 | ```sh 27 | dep deploy main 28 | ``` 29 | 30 | You can specify hosts via the `--hosts` option (comma separate multiple values) and roles via the `--roles` option: 31 | 32 | ```sh 33 | dep deploy --hosts domain.com 34 | dep deploy --roles app 35 | ``` 36 | 37 | ### Simple tasks 38 | 39 | If your task only contains `run` calls, or just one bash command, you can simplify the task definition: 40 | 41 | ```php 42 | task('build', 'npm build'); 43 | ``` 44 | 45 | > By default all simple tasks cd to `release_path`, so you don't need to. 46 | 47 | Or you can use a multi line script: 48 | 49 | ```php 50 | task('build', ' 51 | gulp build; 52 | webpack -p; 53 | echo "Build done"; 54 | '); 55 | ``` 56 | 57 | ### Task grouping 58 | 59 | You can combine tasks in groups: 60 | 61 | ```php 62 | task('deploy', [ 63 | 'deploy:prepare', 64 | 'deploy:update_code', 65 | 'deploy:vendors', 66 | 'deploy:symlink', 67 | 'cleanup' 68 | ]); 69 | ``` 70 | 71 | ### Before and after 72 | 73 | You can define tasks to be run before or after some tasks. 74 | 75 | ``` php 76 | task('deploy:done', function () { 77 | write('Deploy done!'); 78 | }); 79 | 80 | after('deploy', 'deploy:done'); 81 | ``` 82 | 83 | After the `deploy` task is called, `deploy:done` will be executed. 84 | 85 | ### Filtering 86 | 87 | You can specify on which hosts/stages/roles you want to run a task. 88 | 89 | ### By stage 90 | 91 | Filter hosts by stage: 92 | 93 | ``` php 94 | desc('Run tests for application'); 95 | task('test', function () { 96 | ... 97 | })->onStage('test'); 98 | ``` 99 | 100 | ### By roles 101 | 102 | Filter tasks by roles: 103 | 104 | ``` php 105 | desc('Migrate database'); 106 | task('migrate', function () { 107 | ... 108 | })->onRoles('db'); 109 | ``` 110 | 111 | Also you can specify multiple roles: `onRoles('app', 'db', ...)`. 112 | 113 | ### By hosts 114 | 115 | Filter tasks by hosts: 116 | 117 | ``` php 118 | desc('Migrate database'); 119 | task('migrate', function () { 120 | ... 121 | })->onHosts('db.domain.com'); 122 | ``` 123 | 124 | Also you can specify multiple hosts: `onHosts('db.domain.com', ...)`. 125 | 126 | ### Local tasks 127 | 128 | Mark a task with `local` to run it locally and only once, independent from the hosts count. 129 | 130 | ```php 131 | task('build', function () { 132 | ... 133 | })->local(); 134 | ``` 135 | 136 | > Note that calling `run` inside a local task will have the same effect as calling `runLocally`. 137 | 138 | ### Once 139 | 140 | To run a task only once: 141 | 142 | ```php 143 | task('do', ...)->once(); 144 | ``` 145 | 146 | Will run on the first host only. 147 | 148 | ### Reconfigure 149 | 150 | You can reconfigure tasks, e.g. those provided by 3rd party recipes by retrieving them by name: 151 | 152 | ```php 153 | task('notify')->onStage('production'); 154 | ``` 155 | 156 | ### Overriding tasks 157 | 158 | Some times you may want to have a different behavior of some task from the common recipes. Simply override it: 159 | 160 | ```php 161 | task('deploy:update_code', function () { 162 | // Your custom update code 163 | upload(...); 164 | }); 165 | ``` 166 | 167 | ### Using input options 168 | 169 | You can define additional input options and arguments, before defining tasks: 170 | 171 | ``` php 172 | use Symfony\Component\Console\Input\InputOption; 173 | use Symfony\Component\Console\Input\InputArgument; 174 | 175 | argument('stage', InputArgument::OPTIONAL, 'Run tasks only on this host or stage.'); 176 | option('tag', null, InputOption::VALUE_OPTIONAL, 'Tag to deploy.'); 177 | ``` 178 | 179 | To get the input inside a task, this can be used: 180 | 181 | ``` php 182 | task('foo:bar', function() { 183 | // For arguments 184 | $stage = null; 185 | if (input()->hasArgument('stage')) { 186 | $stage = input()->getArgument('stage'); 187 | } 188 | 189 | // For option 190 | $tag = null; 191 | if (input()->hasOption('tag')) { 192 | $tag = input()->getOption('tag'); 193 | } 194 | }); 195 | ``` 196 | 197 | ### Parallel task execution 198 | 199 | When deploying to multiple hosts, Deployer will run one task on each host: 200 | 201 | task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1 202 | 203 | To speedup deployment add the `--parallel` or `-p` option. This will run tasks in parallel on each host. If execution of the task on a host takes longer then on others, Deployer will wait until all hosts have finished their tasks. 204 | 205 | task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1 206 | 207 | Limit the number of concurrent tasks by specifing a number. By default, up to 10 tasks will be processed concurrently. 208 | 209 | ```sh 210 | dep deploy --parallel --limit 2 211 | ``` 212 | 213 | task 2task 2task 2task 2task 1task 1task 1task 1Host 4Host 3Host 2Host 1 214 | 215 | Next: [hosts](hosts.md). 216 | --------------------------------------------------------------------------------