mirror_php/deployer
1
0
Fork 0
mirror of https://github.com/deployphp/deployer.git synced 2025-01-29 11:19:16 +01:00
Code Issues Projects Releases Wiki Activity

Update documentation, improve language, fix grammar and typos (#3657)

Browse Source
This commit is contained in:
Rafael Schwemmer 2023-07-29 12:02:46 +02:00 committed by GitHub
parent 37eef8489b
commit 9b987d4a1e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 104 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/KNOWN_BUGS.md
View File

@ -2,9 +2,9 @@
## Ubuntu 14.04, Coreutils 8.21
There are known bug with relative symlinks `ln --relative`, which may fail rollback command.
There are known bugs with relative symlinks `ln --relative`, which may cause the rollback command to fail.
Add next line to _deploy.php_ file:
Add the following line to your _deploy.php_ file:
```php
set('use_relative_symlink', false);

51
docs/basics.md
View File

@ -15,17 +15,17 @@ $ dep deploy deployer.org
`------------------ CLI
```
Deployer uses the [selector](selector.md) to choose hosts. Next takes the given
Deployer uses the [selector](selector.md) to choose hosts. Next, it takes the given
task, performs some preparation (described later), and executes the task on all
selected hosts.
If selector not specified Deployer will ask you to choose host from list.
If a selector is not specified, Deployer will ask you to choose a host from a list.
If your recipe contains only one host, Deployer will automatically choose it.
To select all hosts specify a special selector: `all`.
To select all hosts, specify a special selector: `all`.
The `dep` CLI looks for `deploy.php` or `deploy.yaml` file in current directory.
The `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory.
Or recipe can be specified explicitly via `-f` or `--file` option.
Or a recipe can be specified explicitly via `-f` or `--file` option.
```
$ dep --file=deploy.php deploy deployer.org
@ -34,8 +34,8 @@ $ dep --file=deploy.php deploy deployer.org
Let's write a recipe.
```php
// We are going to use functions declared primarily in Deployer namespace,
// to simplify recipe we will use Deployer namespace too. Alternativly,
// We are going to use functions declared primarily in the Deployer namespace,
// to simplify the recipe, we will also use the Deployer namespace. Alternatively,
// you can import individual functions via "use function".
namespace Deployer;
@ -55,7 +55,7 @@ $
```
But where is our `whoami` command output? By default, Deployer runs with normal verbosity
level and shows only names of executed tasks. Let's increase verbosity to verbose, and
level and shows only the names of executed tasks. Let's increase verbosity to verbose, and
rerun our task.
Add `-v` option to increase verbosity. Read more about [CLI usage](cli.md).
@ -68,15 +68,15 @@ task my_task
$
```
Now let's add second host:
Now let's add a second host:
```php
host('deployer.org');
host('medv.io');
```
How does Deployer know how to connect to a host? It uses same `~/.ssh/config` file as
the `ssh` command. Alternatively, you can specify [connection options](hosts.md) in recipe.
How does Deployer know how to connect to a host? It uses the same `~/.ssh/config` file as
the `ssh` command. Alternatively, you can specify [connection options](hosts.md) in the recipe.
Let's run `my_task` task on both hosts:
@ -101,7 +101,9 @@ task my_task
[medv.io] deployer
```
Limit level also possible to [specified per task](tasks.md#limit).
It is also possible to specify a [limit level](tasks.md#limit) for each individual task.
By specifying the limit level for each task, you can control the degree of parallelism
for each part of your deployment process.
Each host has a configuration: a list of key-value pairs. Let's define our first
configuration option for both our hosts:
@ -113,7 +115,7 @@ host('medv.io')
->set('my_config', 'bar');
```
In the task we can get current executing host with [currentHost](api.md#currenthost) function:
In the task we can get the currently executing host using the [currentHost](api.md#currenthost) function:
```php
task('my_task', function () {
@ -122,7 +124,7 @@ task('my_task', function () {
});
```
Or with [get](api.md#get) function:
Or with the [get](api.md#get) function:
```diff
task('my_task', function () {
@ -132,11 +134,11 @@ task('my_task', function () {
});
```
Or via [parse](api.md#parse) function which replaces brackets `{{ ... }}` and value
with of config option.
Or via the [parse](api.md#parse) function which replaces the `{{ ... }}` brackets
and their enclosed values with the corresponding configuration option.
All functions (writeln, run, runLocally, cd, upload, etc) call **parse** function
internally. So you don't need to call **parse** function by your self.
All functions (writeln, run, runLocally, cd, upload, etc) call the **parse** function
internally. So you don't need to call the **parse** function by yourself.
```diff
task('my_task', function () {
@ -167,8 +169,9 @@ host('medv.io');
The config option `my_config` will be equal to `global` on both hosts.
Also, config option value can be specified as a callback, such callback
executed on first access and returned result saved in host configuration.
Additionally, the value of a config option can be defined as a callback.
This callback is executed upon its first access, and the returned result
is then stored in the host configuration.
```php
set('whoami', function () {
@ -189,9 +192,11 @@ task my_task
[medv.io] Who am I? anton
```
We can use this to create dynamic configuration which uses current host information.
We can use this to create a dynamic configuration which uses information from the current host.
Only the first call will trigger the callback execution. All subsequent checks use the previously
saved value.
Only the first call will trigger the callback execution. All subsequent checks use saved value.
Here is an example:
@ -207,7 +212,7 @@ task('my_task', function () {
});
```
If we run my_task we will see that `date` is called only once on
If we run my_task, we will see that `date` is called only once on
`{{current_date}}` access.
```

8
docs/ci-cd.md
View File

@ -44,15 +44,15 @@ deploys.
## GitLab CI/CD
Set the following variables in GitLab project:
Set the following variables in your GitLab project:
- `SSH_KNOWN_HOSTS`: Content of `~/.ssh/known_hosts` file.
The public SSH keys for a host may be obtained using the utility `ssh-keyscan`.
For example: `ssh-keyscan deployer.org`.
- `SSH_PRIVATE_KEY`: Private key for connecting to remote hosts.
To generate private key: `ssh-keygen -t ed25519 -C 'gitlab@deployer.org'`.
To generate a private key: `ssh-keygen -t ed25519 -C 'gitlab@deployer.org'`.
Create .gitlab-ci.yml file with following content:
Create a .gitlab-ci.yml file with the following content:
```yml
stages:
@ -84,7 +84,7 @@ In addition, you can ensure that older deployment jobs are cancelled automatical
### Deploy secrets
Is not recommended committing secrets in the repository, you could use a GitLab variable to store them.
It is not recommended to commit secrets to the repository, you could use a GitLab variable to store them instead.
Many frameworks use dotenv to store secrets, let's create a GitLab file variable named `DOTENV`, so it can be deployed along with the code.

17
docs/cli.md
View File

@ -1,19 +1,19 @@
# CLI Usage
We recommend adding next alias to your .bashrc file:
We recommend adding the following alias to your .bashrc file:
```bash
alias dep='vendor/bin/dep'
```
As well as installing completion script for Deployer, completion supports:
It is also recommended to install the completion script for Deployer. Completion supports:
- tasks,
- options,
- host names,
- and configs.
For example for macOS run next commands:
For example, on macOS run the following commands:
```bash
brew install bash-completion
@ -50,7 +50,8 @@ dep run 'uptime -p'
## Tree command
Deployer has group tasks and before/after hooks, so see task tree use **dep tree** command:
Deployer supports [task grouping](tasks.md#task-grouping) and [before/after hooks](tasks.md#addbefore).
To visualize the task hierarchy, use the **dep tree** command.
```
$ dep tree deploy
@ -80,8 +81,8 @@ The task-tree for deploy:
## Execution plan
Before executing tasks, Deployer needs to flatten task tree and to decide in which order it will be executing tasks
on which hosts. Use `--plan` option to output table with tasks/hosts:
Before executing tasks, Deployer needs to flatten the task tree and decide in which order it will be executing tasks
on which hosts. Use the `--plan` option to output a table with tasks/hosts:
```
$ dep deploy --plan all
@ -121,14 +122,14 @@ task('deploy:symlink')->limit(1);
## The `runLocally` working dir
By default `runLocally()` commands are executed relative to the recipe file directory.
By default, `runLocally()` commands are executed relative to the recipe file directory.
This can be overridden globally by setting an environment variable:
```
DEPLOYER_ROOT=. dep taskname`
```
Alternatively the root directory can be overridden per command via the cwd configuration.
Alternatively, the root directory can be overridden per command via the cwd configuration.
```php
runLocally('ls', ['cwd' => '/root/directory']);

37
docs/getting-started.md
View File

@ -2,10 +2,10 @@
In this tutorial we will cover:
- Setting up a new host with provision recipe.
- Setting up a new host with the [provision](recipe/provision.md) recipe.
- Configuring a deployment and perfoming our first deploy.
First, [install the Deployer](installation.md):
First, [install Deployer](installation.md):
Now lets cd into the project and run the following command:
@ -13,7 +13,7 @@ Now lets cd into the project and run the following command:
dep init
```
Deployer will ask you a few question and after finishing you will have a
Deployer will ask you a few questions, and after finishing you will have a
**deploy.php** or **deploy.yaml** file. This is our deployment recipe.
It contains hosts, tasks and requires other recipes. All framework recipes
that come with Deployer are based on the [common](recipe/common.md) recipe.
@ -27,18 +27,18 @@ If you already have a configured webserver you may skip to
Let's create a new VPS on Linode, DigitalOcean, Vultr, AWS, GCP, etc.
Make sure the image is **Ubuntu 20.04 LTS** as this version is supported via
Deployer [provision](recipe/provision.md) recipe.
Make sure the image is **Ubuntu 20.04 LTS** as this version is supported by
Deployer's [provision](recipe/provision.md) recipe.
:::tip
Configure Reverse DNS or RDNS on your server. This will allow you to ssh into
server using the domain name instead of the IP address.
the server using the domain name instead of the IP address.
:::
Our **deploy.php** recipe contains a host definition with few important params:
Our **deploy.php** recipe contains a host definition with a few important params:
- `remote_user` user's name for ssh connection,
- `deploy_path` host's path where we are going to deploy.
- `remote_user` the user name for the ssh connection,
- `deploy_path` the file path on the host where we are going to deploy.
Let's set `remote_user` to be `deployer`. Right now our new server probably only has the `root` user. The provision recipe will
create and configure a `deployer` user for us.
@ -58,8 +58,8 @@ Host *
IdentityFile ~/.ssh/id_rsa
```
Now let's provision our server. As our host doesn't have user `deployer`,
we are going to override `remote_user` for provision via `-o remote_user=root`.
Now let's provision our server. As our host doesn't have a user `deployer`,
we are going to override `remote_user` for provisioning via `-o remote_user=root`.
```sh
dep provision -o remote_user=root
@ -76,8 +76,8 @@ dep provision -o become=root
:::
Deployer will ask you a few questions during provisioning: php version,
database type, etc. Next Deployer will configure our server and create
the `deployer` user. Provision takes around **5 minutes** and will install
database type, etc. Next, Deployer will configure our server and create
the `deployer` user. Provisioning takes around **5 minutes** and will install
everything we need to run a website. A new website will be configured
at [deploy_path](recipe/common.md#deploy_path).
@ -92,16 +92,16 @@ dep deploy
```
If deploy failed, Deployer will print an error message and which command was unsuccessful.
Most likely we need to configure the correct database credentials in _.env_ file or similar.
Most likely we need to configure the correct database credentials in the _.env_ file or similar.
Ssh to the host, for example, for editing _.env_ file:
Ssh to the host, for example, for editing the _.env_ file:
```sh
dep ssh
```
:::tip
If your webserver is using OpenSSH version older than v7.6, updating the code may fail with the error
If your webserver is using an OpenSSH version older than v7.6, updating the code may fail with the error
message `unsupported option "accept-new".` In this case, override the Git SSH command with:
```php
set('git_ssh_command', 'ssh');
@ -140,7 +140,7 @@ location / {
}
```
If you're using provision recipe, Deployer will automatically configure the Caddy
If you're using the [provision recipe](recipe/provision.md), Deployer will automatically configure the Caddy
webserver to serve from the [public_path](/docs/recipe/provision/website.md#public_path).
Now let's add a build step on our host:
@ -168,5 +168,6 @@ task releases
```
:::tip
During development, the [dep push](recipe/deploy/push.md) task maybe useful.
During development, the [dep push](recipe/deploy/push.md) task maybe useful
to create a patch of local changes and push them to the host.
:::

7
docs/hosts.md
View File

@ -85,9 +85,10 @@ Port of remote ssh server to connect to. Default is `22`.
Default is `~/.ssh/config`.
:::info Config file
It is a good practice to keep connection parameters out of `deploy.php` file, as
they can change depending on where the deploy is executed from. Only specify
`hostname` and `remote_user` and other keep in `~/.ssh/config`:
For best practices, avoid storing connection parameters in the `deploy.php file`, as
these can vary based on the deployment execution location. Instead, only include the
hostname and remote_user in `deploy.php`, while maintaining other parameters in the
`~/.ssh/config` file.
```
Host *

30
docs/selector.md
View File

@ -8,7 +8,7 @@ For example, `stage: production` or `role: web`.
You can use labels to select hosts. For example, `dep deploy stage=production`
will deploy to all hosts with `stage: production` label.
Let's define two labels **type** and **env** of our hosts:
Let's define two labels, **type** and **env**, to our hosts:
```php
host('web.example.com')
@ -32,7 +32,7 @@ task('info', function () {
});
```
Now we can run this task on with a selector:
Now we can run this task with a selector:
```bash
$ dep info env=prod
@ -41,8 +41,8 @@ task info
[db.example.com] type:db env:prod
```
As you can see, Deployer will run this task on all hosts with `env: prod` label.
And if we define only `type` label, Deployer will run this task on specified host.
As you can see, Deployer will run this task on all hosts with the `env: prod` label.
And if we define only the `type` label, Deployer will run this task on the specified host.
```bash
dep info type=web
@ -64,7 +64,7 @@ task info
[db.example.com] type:db env:prod
```
As you can see both hosts are selected (as both of them has `env: prod` label).
As you can see, both hosts are selected (as both of them have the `env: prod` label).
We can use `&` to define **AND**. For example, `type=web & env=prod` is a selector
for hosts with `type: web` **AND** `env: prod` labels.
@ -76,7 +76,7 @@ task info
```
We can also use `!=` to negate a label. For example, `type!=web` is a selector for
all hosts what has not `type: web` label.
all hosts which do not have a `type: web` label.
```bash
$ dep info 'type!=web'
@ -86,7 +86,7 @@ task info
:::note
Deployer CLI can take a few selectors as arguments. For example,
`dep info type=web env=prod` is a same as `dep info 'type=web,env=prod'`.
`dep info type=web env=prod` is the same as `dep info 'type=web,env=prod'`.
You can install bash autocompletion for Deployer CLI, which will help you to
write selectors. See [installation](installation.md) for more.
@ -97,9 +97,9 @@ Deployer also has a few special selectors:
- `all` - select all hosts
- `alias=...` - select host by alias
If a selector does not contain `=` sign, Deployer will assume that it is an alias.
If a selector does not contain an `=` sign, Deployer will assume that it is an alias.
For example `dep info web.example.com` is a same as `dep info alias=web.example.com`.
For example `dep info web.example.com` is the same as `dep info alias=web.example.com`.
```bash
$ dep info web.example.com
@ -113,9 +113,9 @@ $ # Same as:
$ dep info 'alias=web.example.com,alias=db.example.com'
````
## Using select() function
## Using the select() function
You can use [select()](api.md#select) function to select hosts by selector from PHP code.
You can use the [select()](api.md#select) function to select hosts by selector in your PHP code.
```php
task('info', function () {
@ -126,7 +126,7 @@ task('info', function () {
});
```
Or you can use [on()](api.md#on) function to run a task on selected hosts.
Or you can use the [on()](api.md#on) function to run a task on selected hosts.
```php
task('info', function () {
@ -138,7 +138,7 @@ task('info', function () {
## Task selectors
To restrict a task to run only on selected hosts, you can use [select()](tasks.md#select) method.
To restrict a task to run only on selected hosts, you can use the [select()](tasks.md#select) method.
```php
task('info', function () {
@ -148,7 +148,7 @@ task('info', function () {
## Labels in YAML
You can also define labels in YAML recipe. For example:
You can also define labels in a YAML recipe. For example:
```yaml
hosts:
@ -160,7 +160,7 @@ hosts:
env: prod
```
But make sure to distinguish between `env` and `labels.env` keys.
But make sure to distinguish between the `env` and `labels.env` keys.
`env` is a configuration key, and `labels.env` is a label.
```php

35
docs/tasks.md
View File

@ -1,6 +1,6 @@
# Tasks
Define a tasks by using the [task](api.md#task) function. Also, you can give a description
Define a task by using the [task](api.md#task) function. Also, you can give a description
for a task with the [desc](api.md#desc) function called before _task_:
```php
@ -10,7 +10,7 @@ task('my_task', function () {
});
```
To get the task or override task config call the _task_ function without second argument:
To get the task or override task config, call the _task_ function without the second argument:
```php
task('my_task')->disable();
@ -28,7 +28,7 @@ task('deploy', function () {
})->desc('Task description');
```
Same as using [desc()](api.md#desc) func helper:
Same as using [desc()](api.md#desc) function helper:
```php
desc('Task description');
@ -39,14 +39,15 @@ task('deploy', function () {
### once()
Sets the task to run only on one of selected hosts.
Sets the task to run only on one of the selected hosts.
### oncePerNode()
Sets the task to run only on **one node** of selected hosts.
Sets the task to run only on **one node** of the selected hosts.
The node is identified by its [hostname](hosts.md#hostname). For instance,
multiple hosts might deploy to a single physical machine (with a unique hostname).
Node determined by [hostname](hosts.md#hostname). For example a few different
hosts can be deploying to one physical machine (uniq hostname).
```php
host('foo')->setHostname('example.com');
@ -61,37 +62,37 @@ task('apt:update', function () {
### hidden()
Hides task from CLI usage page.
Hides the task from CLI usage page.
### addBefore()
Adds before hook to the task.
Adds a before hook to the task.
### addAfter()
Adds after hook to the task.
Adds an after hook to the task.
### limit()
Limits number of hosts the task will be executed in parallel.
Limits the number of hosts the task will be executed on in parallel.
Default is unlimited (runs the task on all host in parallel).
Default is unlimited (runs the task on all hosts in parallel).
### select()
Sets task's host selector.
Sets the task's host selector.
### addSelector()
Adds task's selector.
Adds the task's selector.
### verbose()
Makes task always verbose. As if `-v` option persists.
Makes the task always verbose, as if the `-v` option is persistently enabled.
### disable()
Disables the task. Task will not be executed.
Disables the task. the task will not be executed.
### enable()
@ -126,7 +127,7 @@ after('deploy', 'deploy:done');
After the `deploy` task executed, `deploy:done` will be triggered.
:::note
You can see which hooks is enabled via **dep tree** command.
You can see which hooks are enabled via the **dep tree** command.
```
dep tree deploy

10
docs/yaml.md
View File

@ -1,9 +1,9 @@
# YAML
Deployer supports recipes written in YAML. For validating structure, Deployer uses
JSON Schema declared in [schema.json](https://github.com/deployphp/deployer/blob/master/src/schema.json).
Deployer supports recipes written in YAML. For validating the structure, Deployer uses
the JSON Schema declared in [schema.json](https://github.com/deployphp/deployer/blob/master/src/schema.json).
Here is an example of YAML recipe:
Here is an example of a YAML recipe:
```yaml
import:
@ -26,6 +26,6 @@ after:
deploy:failed: deploy:unlock
```
YAML recipes can include recipes written in PHP. For example, some tasks maybe written in PHP and imported in YAML.
YAML recipes can include recipes written in PHP. For example, some tasks maybe written in PHP and imported into YAML.
Also, other way around is possible: import YAML recipe from PHP. Use [import()](api.md#import) function for that.
Conversely, it's also possible to import a YAML recipe from PHP using the [import()](api.md#import) function.