# Deployment Guide

## Table of Contents

1. [Introduction](#introduction)
2. [Prerequisites](#prerequisites)
3. [Deployment Configuration](#deployment-configuration)
4. [Deployment Steps](#deployment-steps)
5. [Post-Deployment](#post-deployment)
6. [Additional Resources](#additional-resources)

---

## Introduction

Welcome to our project's deployment guide. This document outlines the steps and tools we utilize to ensure a smooth and
efficient deployment process. Leveraging modern deployment tools and practices, we aim to achieve consistent and
reliable deployments across different environments.

---

## Prerequisites

- **Deployer**: We utilize [Deployer](https://deployer.org/), a PHP deployment tool. Ensure you have the latest version
  installed.
- **PHP**: Our deployment scripts are tailored for PHP 8.2. Ensure this version is installed and properly configured,
  especially if you're deploying from your local machine.
- **SSH Configuration**: Before starting the deployment, ensure the `hosts.yml` file is correctly set up. This file
  holds our SSH configurations in `~/.ssh/config` and is crucial for a successful deployment:
    ```
    Host PREPROD-media_manager
    # Ip or domain
    HostName #XXX.XXX.XXX.XXX#
    User #User#
    IdentityFile /home/#YourUser#/.ssh/id_rsa
    Port #PORT#
    ```
---

## Deployment Configuration

- **Deployment Script**: Our deployment strategy revolves around the `deploy.php` script. This script defines the
  deployment steps and rules, ensuring a consistent deployment process across all environments.
- **Deployment Environments**: We deploy to various environments, each with its unique configurations. For a detailed
  overview, refer to the [environment.md](./docs/technical/environment.md) documentation.
- **CI/CD Integration**: Our continuous integration and deployment processes are managed through Bitbucket Pipelines.
  For a detailed workflow, please refer to the [bitbucket-pipelines.yml](./bitbucket-pipelines.yml) file.

---

## CI/CD Deployment (Default strategy)

1. **Pull Request & CI/CD Trigger**:
    - Open a Pull Request (PR) from your feature or fix `BRANCH` to the target environment branch, such
      as `release/development` or any other environment-specific branch.
    - Upon merging the PR, the Bitbucket Pipelines gets triggered, initiating the deployment process for the
      corresponding environment.

2. **CI/CD Monitoring**:
    - Monitor the deployment progress in the [bitbucket-pipelines.yml](./bitbucket-pipelines.yml) dashboard on
      Bitbucket. This ensures that the CI/CD process runs smoothly and any potential issues are promptly addressed.

---

## Manual Deployment (For emergency)

1. **Environment Selection**:
    - Start by determining the desired deployment environment. Options include `dev`, `qa`, `candidate`, or `prod`.

2. **Pull Request & CI/CD Trigger**:
    - Open a Pull Request (PR) from your feature or fix `BRANCH` to the target environment branch, such
      as `release/development` or any other environment-specific branch.
    - Upon merging the PR, the Bitbucket Pipelines gets triggered, initiating the deployment process for the
      corresponding environment.

3. **Deployment Initialization**:
    - Use case: 
       ```bash
      dep deploy stage=${ENV=prod|candidate|qa|dev} --tag=${TAG} -vv
      ```
    - Deployer manages the deployment process. For the `candidate` environment, for instance, use the command:
      ```bash
      dep deploy stage=candidate --tag=2.05.5-rc -vv
      ```
      _The tag can be the branch name or a commit_
    - Adjust the `stage` parameter to match your target environment if it's different from `candidate`.
    - No migration mode. You can add param --no-migrate:
      ```bash
      dep deploy stage=candidate --tag=2.05.5-rc -vv --no-migrate
      ```
---

## Post-Deployment

Once deployment is successful:

- **Application Testing**: Conduct a comprehensive test of the application in the deployed environment to ensure all
  features and functionalities are intact.
- **Monitoring & Logging**: Continuously monitor application logs and performance metrics. This proactive approach helps
  in early detection and resolution of potential issues.

---
## What is Deployer ?

Deployer is a PHP-based deployment tool that offers a series of predefined tasks to streamline the deployment process.
Our project leverages Deployer's capabilities, particularly the `deploy.php` configuration file, to define and execute
deployment tasks.

### The `deploy` Task Breakdown

The `deploy` task in `deploy.php` is a sequence of sub-tasks that are executed in order to deploy our application.
Here's a detailed breakdown:

- **deploy:info**: Displays the deployment information.
- **deploy:prepare**: Prepares the server for deployment, ensuring all necessary directories are present.
- **deploy:lock**: Locks the deployment, preventing concurrent deployments.
- **deploy:release**: Creates a new release directory.
- **deploy:update_code**: Updates the codebase, typically by cloning the latest version from a version control system.
- **deploy:shared**: Sets up shared directories and files.
- **deploy:writable**: Ensures that certain directories/files are writable.
- **deploy:specific**: Handles project-specific tasks.
- **deploy:copy_dirs**: Copies directories from the previous release.
- **deploy:vendors**: Installs the project dependencies.
- **deploy:deployer-helper**: Assists in the deployment process.
- **deploy:owner**: Sets the correct file ownership.
- **deploy:cache:clear**: Clears the application cache.
- **deploy:clear_paths**: Removes unnecessary files and directories.
- **deploy:migrate:media-manager**: Handles the media manager migrations.
- **deploy:migrate:licence**: Manages the licence migrations.
- **deploy:symlink**: Links the release to the "current" directory.
- **deploy:unlock**: Unlocks the deployment, allowing further deployments.
- **cleanup**: Cleans up old releases.
- **deploy:redis:flushall**: Flushes the Redis cache.
- **reload:php-fpm**: Reloads PHP-FPM to apply the changes.
- **success**: Indicates that the deployment was successful.

By understanding each sub-task, developers can gain insights into the deployment process and troubleshoot if necessary.

---

With this structured approach, the deployment process is transparent, allowing for easy modifications and ensuring that
every deployment is consistent and reliable.