## 1. Project Overview & Quickstart (deployphp/installation)
# installation
Open-source repository deployphp/installation
### Repository Details
- **Repository:** [deployphp/installation](https://github.com/deployphp/installation)
- **Primary Language:** Code
*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*
## 2. Official Technical Reference & Guides (deployphp/docs)
## File: README.md
>
> # This is documentation for v6.x version
> ### Documentation for v7.x migrated into [deployer repository](https://github.com/deployphp/deployer/tree/master/docs)
>
# Documentation
## Main Concepts
* [Getting started](getting-started.md)
* [Installation](installation.md)
* [Configuration](configuration.md)
* [Tasks](tasks.md)
* [Hosts](hosts.md)
* [Flow](flow.md)
* [CLI Usage](cli.md)
* [API Reference](api.md)
## Advanced
* [Strategy](advanced/deploy-strategies.md)
* [Deploy and Git](advanced/deploy-and-git.md)
* [Parallel IO](advanced/parallel-io.md)
## How To
* [How to deploy Laravel](how-to-deploy-laravel.md)
## Examples
* [Inventory](examples/inventory.md)
---
## File: api.md
# API Reference
### host
* `host(string ...$hostname): Host`
Define a host or group of hosts. Read more at [hosts](hosts.md).
### localhost
* `localhost(string ...$alias = 'localhost'): Host`
Define a localhost.
### inventory
* `inventory(string $file): Host[]`
Load a list of hosts from a file.
### desc
* `desc(string $description)`
Set a task description.
### task
* `task(string $name, string $script)`
* `task(string $name, callable $callable)`
* `task(string $name): Task`
Define a task or get a task. More at [tasks](tasks.md).
### before
* `before(string $when, string $that)`
Call before `$when` task, `$that` task.
### after
* `after(string $when, string $that)`
Call after `$when` task, `$that` task.
### fail
* `fail(string $what, string $that)`
If task `$what` fails, run `$that` task.
### argument
* `argument($name, $mode = null, $description = '', $default = null)`
Add user's cli arguments.
### option
* `option($name, $shortcut=null, $mode=null, $description='', $default=null)`
Add user's cli options.
### cd
* `cd(string $path)`
Sets the working path for the following `run` functions.
Every task restores the working path to the base working path at the beginning of the task.
~~~php
cd('{{release_path}}');
run('npm run build');
~~~
### within
* `within(string $path, callable $callback)`
Run `$callback` within `$path`.
~~~php
within('{{release_path}}', function () {
run('npm run build');
});
~~~
### workingPath
* `workingPath(): string`
Return the current working path.
~~~php
cd('{{release_path}}');
workingPath() == '/var/www/app/releases/1';
~~~
### run
* `run(string $command, $options = []): string`
Run a command on remote host. Available options:
* `timeout` — Sets the process timeout (max. runtime).
To disable the timeout, set this value to null.
The timeout in seconds (default: 300 sec)
* `tty` — Enables or disables the TTY mode (default: false)
For example, if your private key contains a passphrase, enable tty and you'll see git prompt for a password.
~~~php
run('git clone ...', ['timeout' => null, 'tty' => true]);
~~~
`run` function returns the output of the command as a string:
~~~php
$path = run('readlink {{deploy_path}}/current');
run("echo $path");
~~~
### runLocally
* `runLocally($command, $options = []): string`
Run a command on localhost. Available options:
* `timeout` — The timeout in seconds (default: 300 sec)
* `tty` — The TTY mode (default: false)
### test
* `test(string $command): bool`
Run a test command.
~~~php
if (test('[ -d {{release_path}} ]')) {
...
}
~~~
### testLocally
* `testLocally(string $command): bool`
Run a test command locally.
### on
* `on(Host $host, callable $callback)`
* `on(Host[] $host, callable $callback)`
Execute a `$callback` on the specified hosts.
~~~php
on(host('domain.com'), function ($host) {
...
});
~~~
~~~php
on(roles('app'), function ($host) {
...
});
~~~
~~~php
on(Deployer::get()->hosts, function ($host) {
...
});
~~~
### roles
* `roles(string ...$role): Host[]`
Return a list of hosts by roles.
### invoke
* `invoke(string $task)`
Run a task on the current host.
~~~php
task('deploy', function () {
invoke('deploy:prepare');
invoke('deploy:release');
...
});
~~~
> **Note** this is experimental functionality.
### upload
* `upload(string $source, string $destination, $config = [])`
Upload files from `$source` to `$destination` on the remote host.
~~~php
upload('build/', '{{release_path}}/public');
~~~
> You may have noticed that there is a trailing slash (/) at the end of the first argument in the above command,
> this is necessary to mean "the contents of `build`".
>
> The alternative, without the trailing slash, would place `build`, including the directory, within `public`.
> This would create a hierarchy that looks like: `{{release_path}}/public/build`
Available options:
* `timeout` — The timeout in seconds (default: null)
* `options` — `rsync` options.
### download
* `download(string $source, string $destination, $config = [])`
Download files from the remote host `$source` to `$destination` on the local machine.
Available options:
* `timeout` — The timeout in seconds (default: null)
* `options` — `rsync` options.
### write
Write a message in the output.
You can format the message with the tags `...`, `` or `` (see [Symfony Console](http://symfony.com/doc/current/console/coloring.html)).
### writeln
Same as the `write` function, but also writes a new line.
### set
* `set(string $name, string|int|bool|array $value)`
* `set(string $name, callable $value)`
Setup a global configuration parameter. If callable is passed as `$value` it will be triggered on the first get of this config.
More at [configuration](configuration.md).
### add
* `add(string $name, array $values)`
Add values to already existing config.
More at [configuration](configuration.md).
### get
* `get(string $name, $default = null): string|int|bool|array`
Get a configuration value.
More at [configuration](configuration.md).
### has
* `has(string $name): bool`
Check if a config option exists.
More at [configuration](configuration.md).
### ask
* `ask(string $message, $default = null, $suggestedChoices = null)`
Ask the user for input.
### askChoice
* `askChoice(string $message, array $availableChoices, $default = null, $multiselect = false)`
Ask the user to select from multiple key/value options and return an array.
Multiselect enables selection of multiple comma separated choices.
The default value will be used in quiet mode, otherwise the first available choice will be accepted.
### askConfirmation
* `askConfirmation(string $message, bool $default = false)`
Ask the user a yes or no question.
### askHiddenResponse
* `askHiddenResponse(string $message)`
Ask the user for a password.
### input
* `input(): Input`
Get the current console input.
### output
* `output(): Output`
Get the current console output.
### isQuiet
* `isQuiet(): bool`
Check if th `dep` command was started with the `-q` option.
### isVerbose
* `isVerbose(): bool`
Check if the `dep` command was started with the `-v` option.
### isVeryVerbose
* `isVeryVerbose(): bool`
Check if th `dep` command was started with the `-vv` option.
### isDebug
* `isDebug(): bool`
Check if the `dep` command was started with the `-vvv` option.
### commandExist
* `commandExist(string $command): bool`
Check if a command exists.
~~~php
if (commandExist('composer')) {
...
}
~~~
### parse
* `parse(string $line): string`
Parse config occurrence `{{` `}}` in `$line`.
---
## File: cli.md
# CLI Usage
After [installation](installation.md) of Deployer you will have the ability to run the `dep` command from your terminal.
To get list of all available tasks run the `dep` command. You can run it from any subdirectories of you project;
Deployer will automatically find project root dir.
~~~bash
Deployer
Usage:
command [options] [arguments]
Options:
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
-f, --file[=FILE] Specify Deployer file
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Available commands:
help Displays help for a command
init Initialize deployer system in your project
list Lists commands
run Run any arbitrary command on hosts
self-update Updates deployer.phar to the latest version
ssh Connect to host through ssh
~~~
The best way to configure your `deploy.php` is to automatically deploy to staging on this command:
~~~bash
dep deploy
~~~
This is so somebody can't accidentally deploy to production (for production deployment, the `dep deploy production` command explicitly lists the required production stage).
You need info about available options and usage use the `help` command:
~~~bash
$ dep help deploy
Usage:
deploy [options] [--] []
Arguments:
stage Stage or hostname
Options:
-p, --parallel Run tasks in parallel
-l, --limit=LIMIT How many host to run in parallel?
--no-hooks Run task without after/before hooks
--log=LOG Log to file
--roles=ROLES Roles to deploy
--hosts=HOSTS Host to deploy, comma separated, supports ranges [:]
-o, --option=OPTION Sets configuration option (multiple values allowed)
-h, --help Display this help message
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi Force ANSI output
--no-ansi Disable ANSI output
-n, --no-interaction Do not ask any interactive question
-f, --file[=FILE] Specify Deployer file
--tag[=TAG] Tag to deploy
--revision[=REVISION] Revision to deploy
--branch[=BRANCH] Branch to deploy
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Help:
Deploy your project
~~~
### Overriding configuration options
For example, if your _deploy.php_ file contains this configuration:
~~~php
set('ssh_multiplexing', false);
~~~
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:
~~~bash
dep deploy -o ssh_multiplexing=true
~~~
To override multiple config options, you can pass multiple `-o` args:
~~~bash
dep deploy -o ssh_multiplexing=true -o branch=master
~~~
### Running arbitrary commands
Deployer comes with a command to run any valid command on you server without modifying _deploy.php_
~~~bash
dep run 'ls -la'
~~~
To specify the hosts this command has the corresponding options:
~~~
--stage=STAGE Stage to deploy
--roles=ROLES Roles to deploy
--hosts=HOSTS Host to deploy, comma separated, supports ranges [:]
~~~
### Getting help
You can get more info about any commands by using the help command:
~~~
dep help [command]
~~~
### Autocomplete
Deployer comes with an autocomplete script for bash/zsh/fish, so you don't need to remember all the tasks and options.
To install it run following command:
~~~bash
dep autocomplete
~~~
And follow instructions.
---
## File: configuration.md
# Configuration
To setup a configuration parameter, use `set` function, and to get it inside task use `get` function.
~~~php
set('param', 'value');
task('deploy', function () {
$param = get('param');
});
~~~
Each parameter can be overridden for each host:
~~~php
host(...)
->set('param', 'new value');
~~~
Configuration parameters also can be specified as callback function, which will be executed on remote host on first `get` call:
~~~php
set('current_path', function () {
return run('pwd');
});
~~~
You can use a param's values inside `run` calls with `{{ }}`, instead of doing this:
~~~php
run('cd ' . get('release_path') . ' && command');
~~~
You can do this:
~~~php
run('cd {{release_path}} && command');
~~~
Common recipe comes with a few predefined config params listed below.
To get list of available params run:
~~~sh
dep config:dump
~~~
Show current deployed release:
~~~bash
dep config:current
~~~
Show inventory:
~~~bash
dep config:hosts
~~~
Below is a list of common variables.
### deploy\_path
Where to deploy application on remote host. You should define this variable for all of your hosts.
For example, if you want to deploy your app to home directory:
~~~php
host(...)
->set('deploy_path', '~/project');
~~~
### hostname
Current hostname. Automatically set by `host` function.
### user
Current user name. Defaults to the current git user name:
~~~php
set('user', function () {
return runLocally('git config --get user.name');
});
~~~
You can override it in _deploy.php_ for example to use env var:
~~~php
set('user', function () {
return getenv('DEP_USER');
});
~~~
`user` parameter can be used to configure notification systems:
~~~php
set('slack_text', '{{user}} deploying {{branch}} to {{hostname}}');
~~~
### release\_path
Full path to the current release directory. Current dir path in non-deploy contexts.
Use it as working path for your build:
~~~php
task('build', function () {
cd('{{release_path}}');
// ...
});
~~~
> By default, working path is `release_path` for simple task:
> ~~~php
> task('build', 'webpack -p');
> ~~~
### previous\_release
Points to previous release if it exists. Otherwise variable doesn't exist.
~~~php
task('npm', function () {
if (has('previous_release')) {
run('cp -R {{previous_release}}/node_modules {{release_path}}/node_modules');
}
run('cd {{release_path}} && npm install');
});
~~~
### ssh\_multiplexing
Use [ssh multiplexing](https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Multiplexing) to speedup the native ssh client.
~~~php
set('ssh_multiplexing', true);
~~~
### default\_stage
If the hosts declaration has stages, this option allows you to select the default stage to deploy with `dep deploy`.
~~~php
set('default_stage', 'prod');
host(...)
->stage('prod');
~~~
You can also set callable as an argument if you need some more complex ways to determine default stage.
Having callable in set() allows you to not set the value when declaring it, but later when it is used. There is no difference
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
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.
**Example 1: Direct function assign in set()**
Lets assume that we must include some third party recipe that is setting 'default_stage' like this:
~~~php
set('default_stage', \ThirdPartyVendor\getDefaultStage());
~~~
And we want to overwrite this in our deploy.php with our own value:
~~~php
set('default_stage', \MyVendor\getDefaultStage());
~~~
Third party recipe should avoid a direct function call, because it will be called always even if we overwrite it with
our own set('default_stage', \MyVendor\getDefaultStage()). Look at the next example how the third party recipe should use
callable in that case.
**Example 2: Callable assign in set()**
Lets assume that we must include some third party recipe that is setting 'default_stage' like this:
~~~php
set('default_stage', function() {
return \ThirdPartyVendor\getDefaultStage();
});
~~~
And we want to overwrite this in our deploy.php:
~~~php
set('default_stage', function() {
return \MyVendor\getDefaultStage();
});
~~~
The result is that only \MyVendor\getDefaultStage() is run.
### keep\_releases
Number of releases to keep. `-1` for unlimited releases. Default to `5`.
### repository
Git repository of the application.
To use a private repository, you need to generate a SSH-key on your host and add it to the repository
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.
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
by running `git clone ` on your host and saying `yes` when prompted.
### git\_tty
Allocate TTY for `git clone` command. `false` by default. This allow you to enter a passphrase for keys or add host to `known_hosts`.
~~~php
set('git_tty', true);
~~~
### git\_recursive
Set the `--recursive` flag for git clone. `true` by default. Setting this to `false` will prevent submodules from being cloned as well.
~~~php
set('git_recursive', false);
~~~
### branch
Branch to deploy.
If you want to deploy a specific tag or a revision, you can use `--tag` and `--revision` options while running `dep deploy`. E.g.
~~~bash
dep deploy --tag="v0.1"
dep deploy --revision="5daefb59edbaa75"
~~~
Note that `tag` has higher priority than `branch` and lower than `revision`.
### shared\_dirs
List of shared dirs.
~~~php
set('shared_dirs', [
'logs',
'var',
...
]);
~~~
### shared\_files
List of shared files.
### copy\_dirs
List of files to copy between release.
### writable\_dirs
List of dirs which must be writable for web server.
### writable\_mode
Writable mode
* `acl` (*default*) use `setfacl` for changing ACL of dirs.
* `chmod` use unix `chmod` command,
* `chown` use unix `chown` command,
* `chgrp` use unix `chgrp` command,
### writable\_use\_sudo
Whether to use `sudo` with writable command. Default to `false`.
### writable\_chmod\_mode
Mode for setting `writable_mode` in `chmod`. Default: `0755`.
### writable\_chmod\_recursive
Whether to set `chmod` on dirs recursively or not. Default: `true`.
### http\_user
User the web server runs as. If this parameter is not configured, deployer try to detect it from the process list.
### clear\_paths
List of paths which need to be deleted in release after updating code.
### clear\_use\_sudo
Use or not `sudo` with clear\_paths. Default to `false`.
### cleanup\_use\_sudo
Whether to use `sudo` with `cleanup` task. Default to `false`.
### use\_relative\_symlink
Whether to use relative symlinks. By default deployer will detect if the system supports relative symlinks and use them.
> Relative symlink used by default, if your system supports it.
### use\_atomic\_symlink
Whether to use atomic symlinks. By default deployer will detect if system supports atomic symlinks and use them.
> Atomic symlinking is used by default, if your system supports it.
### composer\_action
Composer action. Default is `install`.
### composer\_options
Options for Composer.
### env
Array of environment variables.
~~~php
set('env', [
'VARIABLE' => 'value',
]);
~~~
Read more about [task definitions](tasks.md).
---
## File: flow.md
# Flow
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.
Each flow is described as a group of other tasks in the `deploy` name space. A common deploy flow may look like this:
~~~php
task('deploy', [
'deploy:prepare',
'deploy:lock',
'deploy:release',
'deploy:update_code',
'deploy:shared',
'deploy:writable',
'deploy:vendors',
'deploy:clear_paths',
'deploy:symlink',
'deploy:unlock',
'cleanup',
'success'
]);
~~~
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.
For example, if you want to run some task before you symlink the new release:
~~~php
before('deploy:symlink', 'deploy:build');
~~~
Or, to send notifications after a successful deployment:
~~~php
after('success', 'notify');
~~~
The next section provides a short overview of each task.
### deploy:prepare
Preparation for deployment. Checks if `deploy_path` exists, otherwise create it. Also checks for the existence of the following paths:
* `releases` – in this dir will be stored the releases.
* `shared` – shared files across all releases.
* `.dep` – metadata used by Deployer.
### deploy:lock
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.
### deploy:release
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.
Also, if in the `deploy_path` there was a previous release symlink, it will be deleted.
### deploy:update_code
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.
Override this task in `deploy.php` to create your own code transfer strategy:
~~~php
task('deploy:update_code', function () {
upload('.', '{{release_path}}');
});
~~~
### deploy:shared
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:
* Copy dir from `release_path` to `shared` if doesn't exists,
* delete dir from `release_path`,
* symlink dir from `shared` to `release_path`.
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.
### deploy:writable
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:
~~~php
set('http_user', 'www-data');
// Or only for specified host:
host(...)
->set('http_user', 'www-data');
~~~
Also this task supports other writable modes:
* chown
* chgrp
* chmod
* acl
To use one of them add this:
~~~php
set('writable_mode', 'chmod');
~~~
To use sudo with writable add this:
~~~php
set('writable_use_sudo', true);
~~~
### deploy:vendors
Install composer dependencies. You can configure composer options with the `composer_options` parameter.
### deploy:clear_paths
Deletes dirs specified in `clear_paths`. This task can be run with sudo using the `clear_use_sudo` parameter.
### deploy:symlink
Switch the `current` symlink to `release_path`. If target system supports atomic switching for symlinks it will used.
### deploy:unlock
Deletes the `.dep/deploy.lock` file. You can run this task directly to delete the lock file:
~~~sh
dep deploy:unlock staging
~~~
### cleanup
Clean up old releases using the `keep_releases` option. `-1` is treated as unlimited releases.
### success
Prints a success message.
---
## File: functions.md
# Functions
Documentation about available function moved to [API Reference](api.md).
> If you are looking for documentation to Deployer 4.x follow [this link](https://github.com/deployphp/docs/tree/4.x).
---
## File: getting-started.md
# Getting Started
First, let's [install Deployer](installation.md). Run the following commands in the terminal:
```sh
curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep
```
Now you can use Deployer via the `dep` command.
Open up a terminal in your project directory and run:
```sh
dep init
```
This command will create the `deploy.php` file in the current directory. It is called a *recipe* and contains configuration and tasks for deployment.
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.
> You can call `dep` command in any subdirectory of your project.
Defining your task is really simple:
```php
task('test', function () {
writeln('Hello world');
});
```
To run that task, run:
```sh
dep test
```
The output will be:
```text
➤ Executing task test
Hello world
✔ Ok
```
Now let's create a task which will run commands on a remote host. For that we must configure deployer.
Your newly created `deploy.php` file should contain a `host` declaration like this:
```php
host('domain.com')
->stage('production')
->set('deploy_path', '/var/www/domain.com');
```
> Also it's possible to declare hosts in a separate yaml file. Find out more about the [inventory](hosts.md#inventory-file).
You can find out more about host configurations [here](hosts.md). Now let's define a task which will output a
`pwd` command from the remote host:
```php
task('pwd', function () {
$result = run('pwd');
writeln("Current dir: $result");
});
```
Run `dep pwd`, and you will get this:
```text
➤ Executing task pwd
Current dir: /var/www/domain.com
✔ Ok
```
Now let's prepare for our first deploy. You need to configure parameters such as `repository`, `shared_files,` and others:
```php
set('repository', 'git@domain.com:username/repository.git');
set('shared_files', [...]);
```
You can return the parameter values in each task using the `get` function.
Also you can override each configuration for each host:
```php
host('domain.com')
...
->set('shared_files', [...]);
```
Read more about [configuring](configuration.md) deploy.
Now let's deploy our application:
```sh
dep deploy
```
To include extra details in the output, you can increase verbosity with the `--verbose` option:
* `-v` for normal output,
* `-vv` for more verbose output,
* `-vvv` for debug.
Deployer will create the following directories on the host:
* `releases` contains releases dirs,
* `shared` contains shared files and dirs,
* `current` symlink to current release.
Configure your hosts to serve your public directory from `current`.
> Note that deployer uses [ACL](https://en.wikipedia.org/wiki/Access_control_list) by default for setting up permissions.
> You can change this behavior with `writable_mode` config.
By default deployer keeps the last 5 releases, but you can increase this number by modifying the associated parameter:
```php
set('keep_releases', 10);
```
If there is an error in the deployment process, or something is wrong with your new release,
simply run the following command to rollback to the previous working release:
```sh
dep rollback
```
You may want to run some task before/after other tasks. Configuring that is really simple!
Let's reload php-fpm after `deploy` finishes:
```php
task('reload:php-fpm', function () {
run('sudo /usr/sbin/service php7-fpm reload');
});
after('deploy', 'reload:php-fpm');
```
If you need to connect to the host, Deployer has a shortcut for faster access:
~~~sh
dep ssh
~~~
This command will connect to selected hosts and cd to `current_path`.
Read more about [configuring](configuration.md) deploy.
---
## File: hosts.md
# Hosts
Defining a host in Deployer is necessary to deploy your application. It can be a remote machine, a local machine or Amazon EC2 instances.
Each host contains a hostname, a stage, one or more roles and configuration parameters.
You can define hosts with the `host` function in `deploy.php` file. Here is an example of a host definition:
~~~php
host('domain.com')
->stage('production')
->roles('app')
->set('deploy_path', '~/app');
~~~
Host *domain.com* has stage `production`, one role `app` and a configuration parameter `deploy_path` = `~/app`.
Hosts can also be described by using yaml syntax. Write this in a `hosts.yml` file:
~~~yaml
domain.com:
stage: production
roles: app
deploy_path: ~/app
~~~
Then to `deploy.php`:
~~~php
inventory('hosts.yml');
~~~
Make sure that your `~/.ssh/config` file contains information about your domains and how to connect.
Or you can specify that information in the `deploy.php` file itself.
~~~php
host('domain.com')
->user('name')
->port(22)
->configFile('~/.ssh/config')
->identityFile('~/.ssh/id_rsa')
->forwardAgent(true)
->multiplexing(true)
->addSshOption('UserKnownHostsFile', '/dev/null')
->addSshOption('StrictHostKeyChecking', 'no');
~~~
> **Best practice** is to leave connecting information for hosts in the `~/.ssh/config` file.
> That way you allow different users to connect in different ways.
### Overriding config per host
For example, if you have some global configuration you can override it per host:
~~~php
set('branch', 'master');
host('prod')
...
->set('branch', 'production');
~~~
Now onthe _prod_ host the branch is set to `production`, on others to `master`.
### Gathering host info
Inside any task, you can get host config with the `get` function, and the host object with the `host` function.
~~~php
task('...', function () {
$deployPath = get('deploy_path');
$host = host('domain.com');
$port = $host->getPort();
});
~~~
### Multiple hosts
You can pass multiple hosts to the `host` function:
~~~php
host('110.164.16.59', '110.164.16.34', '110.164.16.50', ...)
->stage('production')
...
~~~
If your inventory `hosts.yml` file contains multiple, you can change the config for all of them in the same way.
~~~php
inventory('hosts.yml')
->roles('app')
...
~~~
### Host ranges
If you have a lot of hosts following similar patterns, you can describe them like this rather than listing each hostname:
~~~php
host('www[01:50].domain.com');
~~~
For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclusive.
You can also define alphabetic ranges:
~~~php
host('db[a:f].domain.com');
~~~
### Localhost
If you need to build your release before deploying on a remote machine, or deploy to localhost instead of remote,
you need to define localhost:
~~~php
localhost()
->stage('production')
->roles('test', 'build')
...
~~~
### Host aliases
If you want to deploy an app to one host, but for example in different directories, you can describe two host aliases:
~~~php
host('domain.com/green', 'domain.com/blue')
->set('deploy_path', '~/{{hostname}}')
...
~~~
For Deployer, those hosts are different ones, and after deploying to both hosts you will see this directory structure:
~~~
~
└── domain.com
├── green
│ └── ...
└── blue
└── ...
~~~
### One host for a few stages
Often you have only one server for prod and beta stages. You can easily configure them:
~~~php
host('production')
->hostname('domain.com')
->set('deploy_path', '~/domain.com');
host('beta')
->hostname('domain.com')
->set('deploy_path', '~/beta.domain.com');
~~~
Now you can deploy with these commands:
~~~sh
dep deploy production
dep deploy beta
~~~
### Inventory file
Include hosts defined in inventory files `hosts.yml` by `inventory` function:
~~~php
inventory('hosts.yml');
~~~
Here an example of an inventory file `hosts.yml` with the full set of configuration settings
~~~yaml
domain.com:
hostname: domain.com
user: name
port: 22
configFile: ~/.ssh/config
identityFile: ~/.ssh/id_rsa
forwardAgent: true
multiplexing: true
sshOptions:
UserKnownHostsFile: /dev/null
StrictHostKeyChecking: no
stage: production
roles:
- app
- db
deploy_path: ~/app
extra_param: "foo {{hostname}}"
~~~
> **Note** that, as with the `host` function in the *deploy.php* file, it's better to omit information such as
> *user*, *port*, *identityFile*, *forwardAgent* and use it from the `~/.ssh/config` file instead.
If your inventory file contains many similar host definitions, you can use YAML extend syntax:
~~~yaml
.base: &base
roles: app
deploy_path: ~/app
...
www1.domain.com:
<<: *base
stage: production
beta1.domain.com:
<<: *base
stage: beta
...
~~~
Hosts that start with `.` (*dot*) are called hidden and are not visible outside that file.
To define localhost in inventory files add a `local` key:
~~~yaml
localhost:
local: true
roles: build
...
~~~
### Become
Deployer allows you to ‘become’ another user, different from the user that logged into the machine (remote user).
~~~php
host('domain.com')
->become('deployer')
...
~~~
Deployer uses `sudo` privilege escalation method by default.
> **Note** that become doesn't work with `tty` run option.
Next: [deployment flow](flow.md).
---
## File: how-to-deploy-laravel.md
# How to deploy Laravel
Apparently you already have some **Laravel application** and some **server** or **shared hosting**.
Now you need to automate the process of **deployment**.
Deployer will helps you in this as it ships with some ready to use recipes for **Laravel** based application.
Let's start with [installation](installation.md) of Deployer. Run next commands in terminal:
```sh
curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep
```
Next, in your projects directory run:
```sh
dep init -t Laravel
```
Command will create `deploy.php` file for *deploying Laravel*. This file called *recipe* and based on built-in recipe *laravel.php*.
It's contains some host configuration and example task.
First, we need to configure `repository` config of our application:
```php
set('repository', 'git@github.com:user/project.git');
```
Second, configure host:
```php
host('domain.org')
->set('deploy_path', '/var/www/html');
```
Make sure what `~/.ssh/config` contains `domain.org` and you can connect to host using ssh.
Another important parameter it is `deploy_path`, where you project will be located on remote host.
Let's do our first deploy:
```sh
dep deploy
```
If every think goes well, deployer will create next structure on remote host in `deploy_path`:
```text
├── .dep
├── current -> releases/1
├── releases
│ └── 1
└── shared
├── .env
└── storage
```
* `releases` dir contains *deploy* releases of *Laravel* application,
* `shared` dir contains `.env` config and `storage` which will be symlinked to each release,
* `current` is symlink to last release,
* `.dep` dir contains special metadata for deployer (releases log, `deploy.log` file, etc).
Configure you server to serve files from `current`. For example if you are using nginx next:
```config
server {
listen 80;
server_name domain.org;
root /var/www/html/current/public;
location / {
try_files $uri /index.php$is_args$args;
}
}
```
Now you will be able to serve you **laravel project**:
If you want to automatically migrate database, *Laravel* recipe ships with `artisan:migrate` task. Add this lines to your `deploy.php`:
```php
after('deploy:update_code', 'artisan:migrate');
```
More about configuration and task declarations in our [documentation](getting-started.md).
...
---
## File: installation.md
# Installation
There are three ways to install deployer:
1. download phar archive
2. source composer installation
3. distribution composer installation
### Download phar archive
To install Deployer as phar archive, run the following commands:
```sh
curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep
```
If you need another version of Deployer, you can find it on the [download page](https://deployer.org/download).
Later, to upgrade Deployer, run the command:
```sh
dep self-update
```
To upgrade to the next major release, if available, use the `--upgrade (-u)` option:
```sh
dep self-update --upgrade
```
### Source composer installation
To install Deployer source version with Composer, run the command:
```sh
composer require deployer/deployer --dev
```
You can also install it globally:
``` sh
composer global require deployer/deployer
```
More info: https://getcomposer.org/doc/03-cli.md#global
Then to use Deployer, run the following command:
```sh
php vendor/bin/dep
```
> If you have installed Deployer using **both** methods, running `dep` command will prefer a composer-installed version.
> If you have dependency conflicts you can use "distribution composer installation"
### Distribution composer installation
To install Deployer distribution version with Composer, run the command:
```sh
composer require deployer/dist --dev
```
Then to use Deployer, run the following command:
```sh
php vendor/bin/dep
```
### Own builded phar
If you want to build Deployer from the source code, clone the project from GitHub:
```sh
git clone https://github.com/deployphp/deployer.git
```
Then run the following command in the project directory:
```sh
php bin/build
```
This will build the `deployer.phar` phar archive.
### Autocomplete
Deployer comes with an autocomplete script for bash/zsh/fish, so you don't need to remember all tasks and options.
To install, run the following command:
~~~bash
dep autocomplete
~~~
And follow the instructions.
Read [getting started](getting-started.md) next.
---
## File: servers.md
# Servers
Servers was renamed to [hosts](hosts.md) in Deployer 5.x.
If you are looking for documentation to Deployer 4.x follow [this link](https://github.com/deployphp/docs/tree/4.x).
---
## File: tasks.md
# Tasks
Define your own tasks, by using the `task` function. Also, you can setup a description for a task with the `desc` function:
```php
desc('My task');
task('my_task', function () {
run(...);
});
```
To run your task:
```sh
dep my_task
```
To list all available commands:
```sh
dep list
```
To run a task only on a specified host or stage:
```sh
dep deploy main
```
You can specify hosts via the `--hosts` option (comma separate multiple values) and roles via the `--roles` option:
```sh
dep deploy --hosts domain.com
dep deploy --roles app
```
### Simple tasks
If your task only contains `run` calls, or just one bash command, you can simplify the task definition:
```php
task('build', 'npm build');
```
> By default all simple tasks cd to `release_path`, so you don't need to.
Or you can use a multi line script:
```php
task('build', '
gulp build;
webpack -p;
echo "Build done";
');
```
### Task grouping
You can combine tasks in groups:
```php
task('deploy', [
'deploy:prepare',
'deploy:update_code',
'deploy:vendors',
'deploy:symlink',
'cleanup'
]);
```
### Before and after
You can define tasks to be run before or after some tasks.
``` php
task('deploy:done', function () {
write('Deploy done!');
});
after('deploy', 'deploy:done');
```
After the `deploy` task is called, `deploy:done` will be executed.
### Filtering
You can specify on which hosts/stages/roles you want to run a task.
### By stage
Filter hosts by stage:
``` php
desc('Run tests for application');
task('test', function () {
...
})->onStage('test');
```
### By roles
Filter tasks by roles:
``` php
desc('Migrate database');
task('migrate', function () {
...
})->onRoles('db');
```
Also you can specify multiple roles: `onRoles('app', 'db', ...)`.
### By hosts
Filter tasks by hosts:
``` php
desc('Migrate database');
task('migrate', function () {
...
})->onHosts('db.domain.com');
```
Also you can specify multiple hosts: `onHosts('db.domain.com', ...)`.
### Local tasks
Mark a task with `local` to run it locally and only once, independent from the hosts count.
```php
task('build', function () {
...
})->local();
```
> Note that calling `run` inside a local task will have the same effect as calling `runLocally`.
### Once
To run a task only once:
```php
task('do', ...)->once();
```
Will run on the first host only.
### Reconfigure
You can reconfigure tasks, e.g. those provided by 3rd party recipes by retrieving them by name:
```php
task('notify')->onStage('production');
```
### Overriding tasks
Some times you may want to have a different behavior of some task from the common recipes. Simply override it:
```php
task('deploy:update_code', function () {
// Your custom update code
upload(...);
});
```
### Using input options
You can define additional input options and arguments, before defining tasks:
``` php
use Symfony\Component\Console\Input\InputOption;
use Symfony\Component\Console\Input\InputArgument;
argument('stage', InputArgument::OPTIONAL, 'Run tasks only on this host or stage.');
option('tag', null, InputOption::VALUE_OPTIONAL, 'Tag to deploy.');
```
To get the input inside a task, this can be used:
``` php
task('foo:bar', function() {
// For arguments
$stage = null;
if (input()->hasArgument('stage')) {
$stage = input()->getArgument('stage');
}
// For option
$tag = null;
if (input()->hasOption('tag')) {
$tag = input()->getOption('tag');
}
});
```
### Parallel task execution
When deploying to multiple hosts, Deployer will run one task on each host:
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.
Limit the number of concurrent tasks by specifing a number. By default, up to 10 tasks will be processed concurrently.
```sh
dep deploy --parallel --limit 2
```
Next: [hosts](hosts.md).
---
## File: usage-on-windows.md
TODO
* https://msdn.microsoft.com/en-us/commandline/wsl/about
---
## File: advanced/deploy-and-git.md
# Deploy and Git
To clone your repository you need to access your git server.
Check if you have access from your server to github with this command:
~~~bash
ssh git@github.com
~~~
There are two possibilities: deploy keys and agent forwarding.
## Deploy keys
A deploy key is a SSH key set in your repo to grant client read-only access to your repo.
As the name says, its primary function is to be used in the deploy process, where only read access is needed.
Anyone with access to the repository and server will have the ability to deploy the project.
* [Generate a ssh key](https://help.github.com/articles/connecting-to-github-with-ssh/)
* Add the ssh key to the repository's deploy keys setting
> Make sure your repo url uses git protocol not https, which means use `git@github.com:user/repo.git`
## Agent forwarding
In many cases, especially at the beginning of a project,
SSH agent forwarding is the quickest and simplest method to use.
Agent forwarding uses the same SSH keys that your local development computer uses.
**Pros**
* You do not have to generate or keep track of any new keys.
* There is no key management; users have the same permissions on the server that they do locally.
**Cons**
* Automated deploy processes can't be used.
By default, Deployer uses agent forwarding:
~~~php
host(...)
->forwardAgent()
~~~
---
## File: advanced/deploy-strategies.md
# Deploy strategies
### Single server
In most cases you don't need more than one production server.
It's better to build your release files (as cache, js/css bundles) on that machine as well.
So your builds don't depend on your local configuration and can be deployed from everywhere.
By default Deployer recipes are designed to fullfill these kind of deployments.
~~~php
desc('Deploy your project');
task('deploy', [
'deploy:prepare',
'deploy:release',
'deploy:update_code',
'deploy:shared',
'deploy:vendors',
'deploy:symlink',
]);
~~~
### Build server
If you have a lot of servers where are you going to deploy your application, or you are going to use a CI server,
it's better to build your release on one server and then upload files to the application servers.
To do that create a _build_ local task:
~~~php
task('build', function () {
run('composer install');
run('npm install');
run('npm run build');
// ...
})->local();
~~~
> Note, you can use a simple task definition too
> ~~~php
> task('build', '
> composer install
> npm install
> npm run build
> ...
> ');
> ~~~
After create an _upload_ task:
~~~php
task('upload', function () {
upload(__DIR__ . "/", '{{release_path}}');
});
~~~
Next, create release and deploy tasks:
~~~php
task('release', [
'deploy:prepare',
'deploy:release',
'upload',
'deploy:shared',
'deploy:writable',
'deploy:symlink',
]);
task('deploy', [
'build',
'release',
'cleanup',
'success'
]);
~~~
Now you can run the `dep deploy` command.
### Reuse common recipe
If you want to reuse some tasks from the common recipe, make sure that you set the `deploy_path` before invoking tasks.
All common recipe tasks rely on this parameter.
~~~php
task('build', function () {
set('deploy_path', __DIR__ . '/.build');
invoke('deploy:prepare');
invoke('deploy:release');
invoke('deploy:update_code');
invoke('deploy:vendors');
// Add more build steps here
invoke('deploy:symlink');
})->local();
~~~
> Make sure that you set `deploy_path` before invoking tasks.
After create an upload task:
~~~php
task('upload', function () {
upload(__DIR__ . "/.build/current/", '{{release_path}}');
});
~~~
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.
---
## File: advanced/parallel-io.md
# Dealing with IO in parallel mode
If you try to make a task which will be asking a user, for example about a branch,
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.
To workaround this problem, you need to create a local task and ask the user about the branch there:
~~~php
task('what_branch', function () {
$branch = ask('What branch to deploy?');
on(roles('app'), function ($host) use ($branch) {
set('branch', $branch);
});
})->local();
~~~
And call this task before the `deploy` task:
~~~php
before('deploy', 'what_branch');
~~~
Now it should work as expected and the user will be asked for the branch only once.
~~~sh
$ dep deploy -p
➤ Executing task what_branch
What branch to deploy? master
✔ Ok
✔ Executing task deploy:prepare
✔ Executing task deploy:release
...
~~~
---
## File: examples/inventory.md
# Inventory Examples
You can choose any inventory management you want or use one of next examples.
### One or two hosts
In most scenarios your project will have one or two hosts: one for production and one for staging.
So there is no need to separate inventory file, you can write everything in single _deploy.php_ file.
For single host you don't need anything. Deployer will deploy to all defined hosts if no _stage_ parameter specified.
```php
set('deploy_path', '~/project');
host('project.com');
```
If you have one host for production and another for staging the next example is sufficient.
> Right behavior for `dep deploy` command is to _deploy staging_, and to deploy prod is `dep deploy production`.
```php
set('application', 'project');
set('deploy_path', '~/{{application}}');
set('default_stage', 'staging');
host('project.com')
->stage('production');
host('staging.project.com')
->stage('staging');
```
> **Best practice** is to leave connecting information for hosts in the `~/.ssh/config` file.
> That way you allow different users to connect in different ways.
### Separate inventory files
TODO