Update documentation

## Definition of Done

📢 In order to ensure a safe :lock: hub, make sure to complete all the tasks related to the type of work you are doing before merging

*Your issue field isn't here ? Feel free to customize your merge request accordingly!*

### Field: Create or update a job

* [ ] Ensure that the job contain all required files in order to fit [the template](https://gitlab.com/r2devops/hub/-/tree/latest/tools/job_template/job_name)

* [ ] Ensure that the jobs is working

* [ ] Create a new change-log file (initial version must be `0.1.0`)

* [ ] Update the documentation (`README.md` file)

* [ ] Check if your job follows our [guidelines](https://r2devops.io/create-update-job/#guidelines-required) and [best practices](https://r2devops.io/create-update-job/#best-practices-optional)

* [ ] Ensure pipeline doesn't fail

* [ ] Update the dictionary if the job `spell_check` fails, and it's not a typo  

### Field: Update the documentation

* [ ] Check the documentation result is rendered properly in pipeline `MkDocs` artifact

* [ ] Check if your job follows our [guidelines](https://r2devops.io/create-update-job/#guidelines-required) and [best practices](https://r2devops.io/create-update-job/#best-practices-optional)

* [ ] Ensure pipeline doesn't fail

* [ ] Update the dictionary if the job `spell_check` fails, and it's not a typo  

* [ ] Fix the broken links if any is prompted by the `links_checker` job

### Field: Update one of the hub tools

* [ ] Check if your job follows our [guidelines](https://r2devops.io/create-update-job/#guidelines-required) and [best practices](https://r2devops.io/create-update-job/#best-practices-optional)

* [ ] Ensure the tool is working properly locally 

* [ ] Ensure the tool is working properly in the pipeline 

* [ ] If needed, update `Pipfile` (and `Pipfile.lock`) dedicated to the tool

* [ ] Ensure pipeline doesn't fail

* [ ] Ensure you respect the tool quality score 

    * If the tool is in python, try to run `pylint` and get a minimum score of `8.0`

    * If the tool is in javascript, try to run `eslint` and get no error

### Field: Update hub's pipeline 

* [ ] Check if it follows our [guidelines](https://r2devops.io/create-update-job/#guidelines-required) and [best practices](https://r2devops.io/create-update-job/#best-practices-optional)

* [ ] Check if the new pipeline is working properly in a fork

## When I'm done

You are already done :100: ? Well, now put in review one of the R2Devops **team member**, so we can review what you've done so far! :rocket: 

*If you are updating or adding a job, we would be grateful if you could comment in your merge request a direct link to a pipeline with the working job*

codeclimate

sonarcloud

Sonarcloud

deployer

Deployer

jobdescription

      * [x] [R2Devops hub job structure](/job-structure/)

      * [x] [GitLab CI/CD](https://docs.gitlab.com/ee/ci/){:target=blank}

!!! tip

      If you are hesitant about what job to create/update, you can get inspired by our pre-made job issues on Gitlab under the label `Easy first step`, click [here](https://gitlab.com/r2devops/hub/-/issues?label_name%5B%5D=Contributing%3A%3AEasy+first+step){:target=blank} to see.  

## Contributing workflow

Follow the 3 simple steps below to contribute efficiently in the hub. You'll see, it will all go smoothly! 👇

able to work on it before merging your update in the real project.

1. Go on the fork page creation: [`r2devops/hub`](https://gitlab.com/r2devops/hub/-/forks/new).

2. Select the group in which you want to create the fork.

1. Select the group in which you want to create the fork.

### 💻 Step 2: Work in your fork

1. If you want to create a new job:

      1. Make sure that you have NPM installed, more about that [here](https://nodejs.org/en/download/){:target=blank}

      2. Install the package `Cookicutter` by executing this command:

      1. Install the package `Cookicutter` by executing this command:

        ```shell

        npm install -g cookiecutter

        ```

      3. In the `hub` folder, run this command and input the necessary information:

      1. In the `hub` folder, run this command and input the necessary information:

        ```shell

        npx cookiecutter

        ```

    !!! info

        Alternatively, you can do the last steps manually by creating a new directory dedicated to your job in `jobs/` folder if you want to add a new job. You can use the [job template](https://gitlab.com/r2devops/hub/-/tree/latest/tools/job_template/r2_jobname) as a starting point. If you want to modify an existing job, you don't have to create a new directory.

4. Be sure to respect the rules we describe in this guide.

5. Do not update the CI/CD configuration file `.gitlab-ci.yml`.

6. Test your job and ensure it works!

1. Be sure to respect the rules we describe in this guide.

1. Do not update the CI/CD configuration file `.gitlab-ci.yml`.

1. Test your job and ensure it works!

### 🚀 Step 3: Merge request

## Objective

Deploy your PHP project using [Deployer](https://deployer.org/){:target="_blank"}

## How to use it

1. Add this job URL inside the `include` list of your `.gitlab-ci.yml` file (see the [quick setup](/use-the-hub/#quick-setup)). You can specify [a fixed version](#changelog) instead of `latest`.

    ```yaml

      - remote: 'https://jobs.r2devops.io/latest/deployer.yml'

    ```

1. Set the secret variable `SSH_PRIVATE_KEY` and `SSH_KNOWN_HOSTS`as CI/CD variables in [your Gitlab project](https://docs.gitlab.com/ee/ci/variables/README.html#project-cicd-variables){:target="_blank"}

   if you need encrypted variables.  

    !!! info  

        `SSH_KNOWN_HOSTS` needs to contain the same data that we find in the file `.ssh/known_hosts`, this step is needed so that the SSH connection doesn't ask to add the server to `.ssh/known_hosts` as you wouldn't be able to interact with the terminal.  

1. Make sure that you have the deployer config file (`deploy.php` or `deploy.yaml`) in the root folder of your project, More info in [this guide](https://deployer.org/docs/getting-started.html){:target="_blank"}

1. If you need to customize other part of the job (stage, variables, ...) 👉

   check the [jobs customization](/use-the-hub/#jobs-customization)

1. Well done, your job is ready to work ! 😀

### Example of `deploy.php` file

```php

<?php

namespace Deployer;

// Include the Laravel recipe

require 'recipe/laravel.php';

set('application', getenv('CI_PROJECT_NAME')); // Configure from gitlab's env vars

set('ssh_multiplexing', true); // Speed up deployment

// Hosts

host('production.app.com') // Name of the server

    ->hostname('165.22.242.104') // Hostname or IP address

    ->stage('production') // Deployment stage (production, staging, etc)

    ->user('deploy') // SSH user

    ->set('deploy_path', '/var/www'); // Deploy path

// Tasks

desc('Deploy the application');

task('deploy', [

    'deploy:info',

    'deploy:prepare',

    'deploy:lock',

    'deploy:release',

    'deploy:shared',

    'deploy:vendors',

    'deploy:writable',

    'artisan:storage:link', // |

    'artisan:view:cache',   // |

    'artisan:config:cache', // | Laravel specific steps 

    'artisan:optimize',     // |

    'artisan:migrate',      // |

    'deploy:symlink',

    'deploy:unlock',

    'cleanup',

]);

```

## Job details

* Job name: `deployer`

* Docker image: [`edbizarro/gitlab-ci-pipeline-php:7.3-alpine`](https://hub.docker.com/r/edbizarro/gitlab-ci-pipeline-php){:target="_blank"}

* Default stage: `deploy`

* When: `manual`, only when running on default branch (`$CI_DEFAULT_BRANCH`).

  To update this behavior, see [job customization](https://r2devops.io/use-the-hub/#global) to override [`rules`](https://docs.gitlab.com/ee/ci/yaml/#rulesif)

### Variables

!!! info

    All variables can be set using [Gitlab CI/CD

    variables](https://docs.gitlab.com/ee/ci/variables/README.html#project-cicd-variables) to

    avoid exposing them in clear text in your `.gitlab-ci.yml`. This is recommended

    for sensitive parameters such as `SSH_KNOWN_HOSTS` and it's **HIGHLY**

    recommended for secret variable `SSH_PRIVATE_KEY`.

| Name | Description | Mandatory | Default |

| ---- | ----------- | --------- | ------- |

| `SSH_PRIVATE_KEY` | Private SSH key to login on the `host` server | yes | ` `

| `SSH_KNOWN_HOSTS` | List of known_hosts for a seamless deployment | yes | ` `

| `PROJECT_ROOT` | Path to the directory containing `deploy.php` or `deploy.yaml` | no | `.` |

| `DEPLOY_OPTIONS` | Additional options for command `dep deploy` | no | ` ` |

| `DEPLOYER_OUTPUT` | Name for logs file | no | `deployer_output.txt` |

### Artifacts

* If deployment succeeds: the job succeeds with the output as artifact

* If deployment fails: the job fails with the output as artifact

`dep deploy`'s output is available as artifact.

!!! warning

    It's also [exposed

    as](https://docs.gitlab.com/ee/ci/yaml/#artifactsexpose_as){:target="_blank"}

    `Deployer output` in merge requests.  Exposition of artifact currently works

    only if you keep `DEPLOYER_OUTPUT` default value because of [this issue

    from

    Gitlab](https://gitlab.com/gitlab-org/gitlab/-/issues/37129){:target="_blank"}.

    As soon as the issue will be fixed, exposed artifacts will be available

    with any output location.

# Job from R2Devops hub --> r2devops.io

stages:

  - deploy

deployer:

  image: edbizarro/gitlab-ci-pipeline-php:7.3-alpine

  stage: deploy

  variables:

    PROJECT_ROOT: .

    DEPLOY_OPTIONS: ''

    DEPLOYER_OUTPUT: 'deployer_output.txt'

  script:

    # Check if mandatory variables are set

    - if [ -z "$SSH_PRIVATE_KEY" ]; then

    -   echo '[ERROR] You must provide a variable $SSH_PRIVATE_KEY. See documentation -> https://r2devops.io/jobs/deploy/deployer/'

    -   exit 1

    - elif [ -z "$SSH_KNOWN_HOSTS" ]; then

    -   echo '[ERROR] You must provide a variable $SSH_KNOWN_HOSTS. See documentation -> https://r2devops.io/jobs/deploy/deployer/'

    -   exit 1

    - fi

    # Setup ssh

    - mkdir -m 700 -p ~/.ssh

    - eval $(ssh-agent -s)

    - echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts

    - chmod 644 ~/.ssh/known_hosts

    - echo "${SSH_PRIVATE_KEY}" | tr -d '\r' | ssh-add - > /dev/null

    # Install Deployer CLI

    - curl -LO https://deployer.org/deployer.phar && sudo mv deployer.phar /usr/local/bin/dep && chmod +x /usr/local/bin/dep

    # Deploy to your host

    - /usr/local/bin/dep deploy $DEPLOY_OPTIONS >&1 | tee ${DEPLOYER_OUTPUT}

  artifacts:

    when: always

    expose_as: "Deployer output"

    paths:

      - "$DEPLOYER_OUTPUT"

      # Below path is a workaround to provide artifact exposition in MR if

      # default output value is used. See https://r2devops.io/jobs/deploy/ssh/#artifacts

      - "deployer_output.txt"

  rules:

    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

      when: manual