diff --git a/docs/basics.md b/docs/basics.md index f68cd75af..dad213b23 100644 --- a/docs/basics.md +++ b/docs/basics.md @@ -1,44 +1,44 @@ # Basics -Deployer has two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md). +Deployer operates around two main concepts: [**hosts**](hosts.md) and [**tasks**](tasks.md). These are defined within a +**recipe**, which is simply a file containing **hosts** and **tasks** definitions. -A **recipe** is a file containing definitions for **hosts** and **tasks**. +The Deployer CLI requires two arguments: -Deployer CLI requires two arguments to run: a **task** to run and a **selector**. +1. A **task** to execute. +2. A **selector** to determine the hosts the task will run on. -Hosts can also be [selected via labels](hosts.md#labels), also a default host selection can be configured. +Here's an example: -``` +```sh $ dep deploy deployer.org - --- ------ ------------ - | | | - | | `--- Selector - | `------------- Task - `------------------ CLI + ------ ------------ + task selector ``` -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. +Deployer uses the [selector](selector.md) to choose which hosts to execute the task on. After selecting hosts, it +prepares the environment (details later) and runs the task. -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`. +### Host Selection -The `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory. +- If no selector is specified, Deployer prompts you to choose a host. +- If your recipe has only one host, it is automatically selected. +- To run a task on all hosts, use the `all` selector. -Or a recipe can be specified explicitly via `-f` or `--file` option. +By default, the `dep` CLI looks for a `deploy.php` or `deploy.yaml` file in the current directory. Alternatively, you +can specify a recipe file explicitly using the `-f` or `--file` option: -``` +```sh $ dep --file=deploy.php deploy deployer.org ``` -Let's write a recipe. +--- + +## Writing Your First Recipe + +Here's an example of a simple recipe: ```php -// 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; host('deployer.org'); @@ -48,57 +48,56 @@ task('my_task', function () { }); ``` -Let's try to run our task on deployer.org. +To execute this task on `deployer.org`: -``` +```sh $ dep my_task task my_task -$ ``` -If no host is provided and no default_selector is set, Deployer will show an interactive prompt for selecting hosts. -If your recipe contains only one host, Deployer will automatically choose it. -To select all hosts specify `all`. - -But where is our `whoami` command output? By default, Deployer runs with normal verbosity -level and shows only the names of executed tasks. Let's increase verbosity to verbose, and -rerun our task. +### Increasing Verbosity -Add `-v` option to increase verbosity. Read more about [CLI usage](cli.md). +By default, Deployer only shows task names. To see detailed output (e.g., the result of the `whoami` command), use the +`-v` option: -``` +```sh $ dep my_task -v task my_task [deployer.org] run whoami [deployer.org] deployer -$ ``` -Now let's add a second host: +--- + +## Working with Multiple Hosts + +You can define multiple hosts in your recipe: ```php host('deployer.org'); host('medv.io'); ``` -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. +Deployer connects to hosts using the same `~/.ssh/config` file as the `ssh` command. Alternatively, you can +specify [connection options](hosts.md) directly in the recipe. -Let's run `my_task` task on both hosts: +Run a task on both hosts: -``` +```sh $ dep my_task -v all task my_task [deployer.org] run whoami [medv.io] run whoami -[medv.io] anton [deployer.org] deployer +[medv.io] anton ``` -Deployer runs a task in parallel on each host. This is why the output is mixed. -We can limit it to run only on one host at a time. +### Controlling Parallelism -``` +By default, tasks run in parallel on all selected hosts, which may mix the output. To limit execution to one host at a +time: + +```sh $ dep my_task -v all --limit 1 task my_task [deployer.org] run whoami @@ -107,21 +106,20 @@ task my_task [medv.io] deployer ``` -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. +You can also specify a [limit level](tasks.md#limit) for individual tasks to control parallelism. + +--- + +## Configuring Hosts -Each host has a configuration: a list of key-value pairs. Let's define our first -configuration option for both our hosts: +Each host can have a set of key-value configuration options. Here's an example: ```php -host('deployer.org') - ->set('my_config', 'foo'); -host('medv.io') - ->set('my_config', 'bar'); +host('deployer.org')->set('my_config', 'foo'); +host('medv.io')->set('my_config', 'bar'); ``` -In the task we can get the currently executing host using the [currentHost](api.md#currenthost) function: +Access these options in a task using the [currentHost](api.md#currenthost) function: ```php task('my_task', function () { @@ -130,41 +128,28 @@ task('my_task', function () { }); ``` -Or with the [get](api.md#get) function: +Or more concisely with the [get](api.md#get) function: -```diff +```php task('my_task', function () { -- $myConfig = currentHost()->get('my_config'); -+ $myConfig = get('my_config'); + $myConfig = get('my_config'); writeln("my_config: " . $myConfig); }); ``` -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 the **parse** function -internally. So you don't need to call the **parse** function by yourself. +Or using brackets syntax `{{` and `}}`: -```diff +```php task('my_task', function () { -- $myConfig = get('my_config'); -- writeln("my_config: " . $myConfig); -+ writeln("my_config: {{my_config}}"); + writeln("my_config: {{my_config}}"); }); ``` -Let's try to run our task: +--- -``` -$ dep my_task all -task my_task -[deployer.org] my_config: foo -[medv.io] my_config: bar -``` +## Global Configurations -Awesome! Each host configuration inherits global configuration. Let's refactor -our recipe to define one global config option: +Host configurations inherit global options. Here's how to set a global configuration: ```php set('my_config', 'global'); @@ -173,11 +158,23 @@ host('deployer.org'); host('medv.io'); ``` -The config option `my_config` will be equal to `global` on both hosts. +Both hosts will inherit `my_config` with the value `global`. You can override these values for individual hosts as +needed. + + +```php +set('my_config', 'global'); + +host('deployer.org'); +host('medv.io')->set('my_config', 'bar'); +``` + +--- -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. +## Dynamic Configurations + +You can define dynamic configuration values using callbacks. These are evaluated the first time they are accessed, and +the result is stored for subsequent use: ```php set('whoami', function () { @@ -189,22 +186,18 @@ task('my_task', function () { }); ``` -Let's try to run it: +When executed: -``` +```sh $ dep my_task all task my_task [deployer.org] Who am I? deployer [medv.io] Who am I? anton ``` -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. +--- - -Here is an example: +Dynamic configurations are cached after the first use: ```php set('current_date', function () { @@ -218,10 +211,9 @@ task('my_task', function () { }); ``` -If we run my_task, we will see that `date` is called only once on -`{{current_date}}` access. +Running this task: -``` +```sh $ dep my_task deployer.org -v task my_task [deployer.org] run date @@ -231,9 +223,13 @@ task my_task [deployer.org] What time is it? Wed 03 Nov 2021 01:16:53 PM UTC ``` -We can override a config option via CLI option `-o` like this: +--- -``` +## Overriding Configurations via CLI + +You can override configuration values using the `-o` option: + +```sh $ dep my_task deployer.org -v -o current_date="I don't know" task my_task [deployer.org] What time is it? I don't know @@ -241,5 +237,9 @@ task my_task [deployer.org] What time is it? I don't know ``` -Since the `current_date` config option is overridden there is no need to call the callback. -So there is no 'run date'. +Since `current_date` is overridden, the callback is never executed. + +--- + +By now, you should have a solid understanding of Deployer’s basics, from defining tasks and hosts to working with +configurations and dynamic values. Happy deploying! diff --git a/docs/getting-started.md b/docs/getting-started.md index 3eada0db6..72804e317 100755 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,47 +1,48 @@ # Getting Started -In this tutorial we will cover: +This tutorial will guide you through: - Setting up a new host with the [provision](recipe/provision.md) recipe. -- Configuring a deployment and perfoming our first deploy. +- Configuring a deployment and performing your first deploy. -First, [install Deployer](installation.md): +## Step 1: Install Deployer {#install} -Now lets cd into the project and run the following command: +First, [install Deployer](installation.md). Once installed, navigate to your project directory and run: ```sh dep init ``` -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. +Deployer will prompt you with a series of questions. After completing them, you'll have a **deploy.php** or * +*deploy.yaml** file—your deployment recipe. This file defines hosts, tasks, and dependencies on other recipes. +Framework-specific recipes provided by Deployer are based on the [common](recipe/common.md) recipe. -## Provision +--- + +## Step 2: Provision a New Server {#provision} :::note -If you already have a configured webserver you may skip to -[deployment](#deploy). +If you already have a configured web server, skip to [deployment](#deploy). ::: -Let's create a new VPS on Linode, DigitalOcean, Vultr, AWS, GCP, etc. +### Setting Up Your VPS -Make sure the image is **Ubuntu 20.04 LTS** as this version is supported by -Deployer's [provision](recipe/provision.md) recipe. +Create a new VPS with a provider like Linode, DigitalOcean, Vultr, AWS, or GCP. Use an **Ubuntu** image, as it's +supported by Deployer's [provision](recipe/provision.md) recipe. :::tip -Configure a DNS record for your domain that points to the IP address of your server. -This will allow you to ssh into the server using your domain name instead of the IP address. +Set up a DNS record pointing your domain to your server's IP address. This allows you to SSH into the server using your +domain name instead of its IP. ::: -Our **deploy.php** recipe contains a host definition with a few important params: +### Configuring `deploy.php` + +Your **deploy.php** recipe should define your host with key parameters: -- `remote_user` the user name for the ssh connection, -- `deploy_path` the file path on the host where we are going to deploy. +- **`remote_user`**: The SSH username. +- **`deploy_path`**: The file path where your project will be deployed. -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. +Example: ```php host('example.org') @@ -49,16 +50,21 @@ host('example.org') ->set('deploy_path', '~/example'); ``` -To connect to the remote host we need to specify an identity key or private key. -We can add our identity key directly into the host definition, but it's better to put it -in the **~/.ssh/config** file: +If your server only has a `root` user, the `provision` recipe will create and configure a `deployer` user for you. + +### Adding an Identity Key + +To connect to your server, use an identity key or private key. Instead of defining it directly in your host +configuration, add it to your **~/.ssh/config** file: ``` Host * IdentityFile ~/.ssh/id_rsa ``` -Now let's provision our server. +### Provisioning the Server + +Run the following command to provision your server: ```sh dep provision @@ -66,75 +72,68 @@ dep provision :::tip -Deployer uses `root` user by default, but you can change it via `-o provision_user=your-user`. - -If your server doesn't have a `root` user but your remote user can use `sudo` to -become root, then use: - -```sh -dep provision -o become=root -``` +- To change the default `root` user, use: + ```sh + dep provision -o provision_user=your-user + ``` +- If your remote user can `sudo` to become root, use: + ```sh + 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. 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). +During provisioning, Deployer will ask about PHP versions, database preferences, and more. It takes about **5 minutes** +and installs everything required to run a website. The deployment path is configured +as [deploy_path](recipe/common.md#deploy_path). -After we have configured the webserver, let's deploy the project. +--- -## Deploy +## Step 3: Deploy Your Project {#deploy} -To deploy the project: +Deploy your project with: ```sh 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 the _.env_ file or similar. - -Ssh to the host, for example, for editing the _.env_ file: +If the deployment fails, Deployer will display the error and the failed command. You may need to configure your `.env` +file or similar credentials. To edit files directly on the server: ```sh dep ssh ``` -:::tip -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'); -``` -::: - -After everything is configured properly we can resume our deployment from the -place it stopped. However, this is not required; we can just start a new deploy: +If needed, resume deployment from the last step: -``` +```sh dep deploy --start-from deploy:migrate ``` -After our first successful deployment, we can find the following directory structure on our server: +--- + +## Step 4: Post-Deployment Configuration + +After the first successful deployment, the server directory structure looks like this: ``` -~/example // The deploy_path. - |- current -> releases/1 // Symlink to the current release. - |- releases // Dir for all releases. - |- 1 // Actual files location. +~/example // deploy_path + |- current -> releases/1 // Symlink to current release + |- releases // Directory for all releases + |- 1 // Latest release |- ... - |- .env -> shared/.env // Symlink to shared .env file. - |- shared // Dirs for shared files between releases. + |- .env -> shared/.env // Symlink to shared .env file + |- shared // Shared files between releases |- ... - |- .env // Example: shared .env file. - |- .dep // Deployer configuration files. + |- .env // Shared .env file + |- .dep // Deployer configuration files ``` -Configure you webserver to serve the `current` directory. For example, for nginx: +### Web Server Setup -``` +Configure your web server to serve from the `current` directory. Example for Nginx: + +```nginx root /home/deployer/example/current/public; index index.php; location / { @@ -142,10 +141,14 @@ location / { } ``` -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). +For those using the [provision recipe](recipe/provision.md), Deployer will automatically configure the Caddy web server +to serve from the [public_path](recipe/provision/website.md#public_path). + +--- -Now let's add a build step on our host: +## Step 5: Adding a Build Step + +To automate build steps, add a task in your **deploy.php**: ```php task('build', function () { @@ -157,11 +160,19 @@ task('build', function () { after('deploy:update_code', 'build'); ``` -Deployer has a useful task for examining what is currently deployed. +--- + +## Examining Deployments + +Use the `releases` task to view deployment details: + +```sh +dep releases +``` + +Example output: ``` -$ dep releases -task releases +---------------------+--------- deployer.org -------+--------+-----------+ | Date (UTC) | Release | Author | Target | Commit | +---------------------+-------------+----------------+--------+-----------+ @@ -173,3 +184,7 @@ task releases 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. ::: + +--- + +With Deployer, you're now ready to efficiently set up, provision, and manage deployments for your projects! diff --git a/docs/hosts.md b/docs/hosts.md index 921a64906..273b46faf 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -1,45 +1,64 @@ # Hosts -To define a new host use the [host()](api.md#host) function. Deployer keeps a list of -all defined hosts in the `Deployer::get()->hosts` collection. +In Deployer, you define hosts using the [host()](api.md#host) function. + +### Defining a Host ```php host('example.org'); ``` -Each host contains it's own configuration key-value pairs. The [host()](api.md#host) -call defines two important configs: **alias** and **hostname**. +Each host is associated with configuration key-value pairs. When you define a host, two key configurations are set: + +- **`hostname`**: Used for connecting to the remote host. +- **`alias`**: A unique identifier for the host in recipe. -- **hostname** - used when connecting to remote host. -- **alias** - used as a key in `Deployer::get()->hosts` collection. +### Example: Using Host Configurations + +You can access host configurations within tasks with the [currentHost()](api.md#currenthost) function: ```php task('test', function () { - writeln('The {{alias}} is {{hostname}}'); + $hostname = currentHost()->get('hostname'); + $alias = currentHost()->get('alias'); + writeln("The $alias is $hostname"); }); ``` +Or using brackets syntax: + +```php +task('test', function () { + writeln('The {{alias}} is {{hostname}}'); +}); ``` + +Running the task: + +```sh $ dep test [example.org] The example.org is example.org ``` -We can override hostname via `set()` method: +### Overriding Hostname + +You can override the default hostname with the `set()` method: ```php host('example.org') ->set('hostname', 'example.cloud.google.com'); ``` -The hostname will be used for the ssh connection, but the host will be referred -by its alias when running Deployer. +Now the `hostname` is used for SSH connections, but the `alias` remains unchanged: -``` +```sh $ dep test [example.org] The example.org is example.cloud.google.com ``` -Another important ssh connection parameter is `remote_user`. +### Configuring Remote User + +Specify the `remote_user` to define which user to connect as: ```php host('example.org') @@ -47,11 +66,9 @@ host('example.org') ->set('remote_user', 'deployer'); ``` -Now Deployer will connect using something like -`ssh deployer@example.cloud.google.com` to establishing connection. +Deployer will now connect using `ssh deployer@example.cloud.google.com`. -Also, Deployer's `Host` class has special setter methods (for better IDE -autocompletion). +Alternatively, you can use special setter methods for better IDE autocompletion: ```php host('example.org') @@ -59,180 +76,114 @@ host('example.org') ->setRemoteUser('deployer'); ``` -## Host labels +--- -Hosts can receive labels to identify a subselection of all available hosts. This is a flexible approach to manage and deploy multiple hosts. -The label names and values can be chosen freely. For example, a stage name can be applied: +## Host Labels -```php -host('example.org') - ->setLabels(['stage' => 'prod']) -; - -host('staging.example.org') - ->setLabels(['stage' => 'staging']) -; +Labels allow you to group and identify hosts for specific deployments. Labels are defined as key-value pairs: +```php +host('example.org')->setLabels(['stage' => 'prod']); +host('staging.example.org')->setLabels(['stage' => 'staging']); ``` -The example above can be simplified without labels, by giving the host prod and staging as name, and using setHostname(...). -But for for multi server setups, labels become much more powerful: +Labels become powerful in multi-server setups: ```php -host('admin.example.org') - ->setLabels(['stage' => 'prod', 'role' => 'web']) -; - -host('web[1:5].example.org') - ->setLabels(['stage' => 'prod', 'role' => 'web']) -; - -host('db[1:2].example.org') - ->setLabels(['stage' => 'prod', 'role' => 'db']) -; - -host('test.example.org') - ->setLabels(['stage' => 'test', 'role' => 'web']) -; - -host('special.example.org') - ->setLabels(['role' => 'special']) -; +host('admin.example.org')->setLabels(['stage' => 'prod', 'role' => 'web']); +host('web[1:5].example.org')->setLabels(['stage' => 'prod', 'role' => 'web']); +host('db[1:2].example.org')->setLabels(['stage' => 'prod', 'role' => 'db']); +host('test.example.org')->setLabels(['stage' => 'test', 'role' => 'web']); +host('special.example.org')->setLabels(['role' => 'special']); ``` -When calling `dep deploy`, you can filter the hosts to deploy by passing a select string: +### Filtering Hosts by Labels -``` +When deploying, you can filter hosts using label selectors: + +```sh $ dep deploy stage=prod&role=web,role=special ``` -To check for multiple labels that have to be set on the same host, you can use the `&` operator. -To add another selection, you can use `,` as a separator. +- Use `&` to specify multiple labels that must match on the same host. +- Use `,` to separate multiple selections. -Also you can configure a default selection string, that is used when running 'dep deploy' without arguments. +Set a default selection string for convenience: ```php set('default_selector', "stage=prod&role=web,role=special"); ``` +--- -## Host config - -### `alias` - -The identifier used to identify a host. -You can use actual hostname or something like `prod` or `staging`. - -### `hostname` - -Deployer uses this config for actual ssh connection. +## Host Configurations -### `remote_user` +### Key Host Configurations -Deployer uses this config for actual ssh connection. If not specified, -Deployer will be using `RemoteUser` from **~/.ssh/config** file, or current -OS username. +| Config Key | Description | +|------------------------|------------------------------------------------------------------------------------------------| +| **`alias`** | Identifier for the host (e.g., `prod`, `staging`). | +| **`hostname`** | Actual hostname or IP address used for SSH connections. | +| **`remote_user`** | SSH username. Defaults to the current OS user or `~/.ssh/config`. | +| **`port`** | SSH port. Default is `22`. | +| **`config_file`** | SSH config file location. Default is `~/.ssh/config`. | +| **`identity_file`** | SSH private key file. E.g., `~/.ssh/id_rsa`. | +| **`forward_agent`** | Enable SSH agent forwarding. Default is `true`. | +| **`ssh_multiplexing`** | Enable SSH multiplexing for performance. Default is `true`. | +| **`shell`** | Shell to use. Default is `bash -ls`. | +| **`deploy_path`** | Directory for deployments. E.g., `~/myapp`. | +| **`labels`** | Key-value pairs for host selection. | +| **`ssh_arguments`** | Additional SSH options. E.g., `['-o UserKnownHostsFile=/dev/null']`. | +| **`ssh_control_path`** | Control path for SSH multiplexing. Default is `~/.ssh/%C` or `/dev/shm/%C` in CI environments. | -### `port` +### Best Practices -Port of remote ssh server to connect to. Default is `22`. - -### `config_file` - -Default is `~/.ssh/config`. - -:::info Config file -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. +Avoid storing sensitive SSH connection parameters in `deploy.php`. Instead, configure them in `~/.ssh/config`: ``` Host * IdentityFile ~/.ssh/id_rsa ``` -::: - -### `identity_file` - -For example, `~/.ssh/id_rsa`. - -### `forward_agent` - -SSH forwarding is a way to securely tunnel network connections from your local computer to a remote server, and from the remote server to another destination. There are several types of SSH forwarding, including local, remote, and dynamic forwarding. SSH agent forwarding is a specific type of local forwarding that allows you to use your local SSH keys to authenticate on remote servers. This can be useful if you want to use your local SSH keys to connect to a remote server, but don't want to copy your keys to the remote server. - -Default is `true`. - -### `ssh_multiplexing` - -SSH multiplexing is a technique that allows a single Secure Shell (SSH) connection to be used for multiple interactive sessions or for multiple tunneled connections. This can be useful in a number of situations, such as when you want to open multiple terminal sessions to a remote server over a single SSH connection, or when you want to establish multiple secure connections to a remote server but don't want to open multiple SSH connections. - -Default is `true`. - -### `shell` - -Default is `bash -ls`. - -### `deploy_path` +--- -For example, `~/myapp`. +## Advanced Host Definitions -### `labels` +### Multiple Hosts -Key-value pairs for host selector. - -### `ssh_arguments` - -For example, `['-o UserKnownHostsFile=/dev/null']` - -### `ssh_control_path` - -Default is `~/.ssh/%C`. - -If **CI** env is present, default value is `/dev/shm/%C`. - -## Multiple hosts - -You can pass multiple hosts to the host function: +Define multiple hosts in one call: ```php -host('example.org', 'deployer.org', ...) - ->setRemoteUser('anton'); +host('example.org', 'deployer.org', 'another.org')->setRemoteUser('anton'); ``` -## Host ranges +### Host Ranges -If you have a lot of hosts following similar patterns, you can describe them -like this rather than listing each hostname: +For patterns with many hosts, use ranges: ```php -host('www[01:50].example.org'); +host('www[01:50].example.org'); // Will define hosts "www01.example.org", "www02.example.org", etc. +host('db[a:f].example.org'); // Will define hosts "dba.example.org", "dbb.example.org", etc. ``` -For numeric patterns, leading zeros can be included or removed, as desired. -Ranges are inclusive. +- Numeric ranges can include leading zeros. +- Alphabetic ranges are also supported. -You can also define alphabetic ranges: +### Localhost -```php -host('db[a:f].example.org'); -``` - -## Localhost - -The [localhost()](api.md#localhost) function defines a special local host. -Deployer will not connect to this host, but will execute commands locally instead. +Use the [localhost()](api.md#localhost) function for local execution: ```php -localhost(); // Alias and hostname will be "localhost". +localhost(); // Alias and hostname are "localhost". localhost('ci'); // Alias is "ci", hostname is "localhost". ``` -## YAML Inventory +Now [run()](api.md#run) will execute on command locally. Alternatively, you can use [runLocally()](api.md#runlocally) +function. -You can use the [import()](api.md#import) function to keep host definitions in a -separate file. For example, _inventory.yaml_. +### YAML Inventory + +Separate host definitions into an external file using the [import()](api.md#import) function: ```php title="deploy.php" import('inventory.yaml'); @@ -245,3 +196,8 @@ hosts: deployer.org: remote_user: deployer ``` + +--- + +With these tools and configurations, you can manage and deploy to hosts effectively, whether it's a single server or a +complex multi-host setup. Happy deploying! diff --git a/docs/selector.md b/docs/selector.md index 349f88377..12dad1b45 100644 --- a/docs/selector.md +++ b/docs/selector.md @@ -1,11 +1,11 @@ # Selector -Deployer uses the selector to choose hosts. Each host can have a set of labels. -Labels are key-value pairs. +Deployer uses the selector to choose hosts. Each host can have a set of labels. +Labels are key-value pairs. -For example, `stage: production` or `role: web`. +For example, `stage: production` or `role: web`. -You can use labels to select hosts. For example, `dep deploy stage=production` +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**, to our hosts: @@ -53,18 +53,8 @@ task info ## Selector syntax -Label syntax is represented by [disjunctive normal form](https://en.wikipedia.org/wiki/Disjunctive_normal_form) -(**OR of ANDs**). -``` -(condition1 AND condition2) OR (condition3 AND condition4) -``` - -Each condition in the subquery that is represented by [conjunctive normal form](https://en.wikipedia.org/wiki/Conjunctive_normal_form) -``` -(condition1 OR condition2) AND (condition3 OR condition4) -``` - -### Explanation +Selector syntax consists of a list of conditions, separated by `,` or `&`. There comma means **OR** +and `&` means **AND**. For example, `type=web,env=prod` is a selector of: `type=web` **OR** `env=prod`. @@ -93,6 +83,7 @@ for hosts with (`type: web` **OR** `type: db`) **AND** `env: prod` labels. $ dep info 'type=web|db & env=prod' task info [web.example.com] type:web env:prod +[db.example.com] type:db env:prod ``` We can also use `!=` to negate a label. For example, `type!=web` is a selector for @@ -104,8 +95,8 @@ task info [db.example.com] type:db env:prod ``` -:::note -Deployer CLI can take a few selectors as arguments. For example, +:::note +Deployer CLI can take a few selectors as arguments. For example, `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