From 258f4d0e2e345fddb839269755b242b3e63754f5 Mon Sep 17 00:00:00 2001
From: Jamie Schouten <jamie@qlic.nl>
Date: Sat, 14 Sep 2024 19:47:29 +0200
Subject: [PATCH] add readme

---
 README.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9cc39c5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,114 @@
+# Deploy Workflow
+
+This is a workflow designed to handle automated deployment tasks. It leverages Docker containers, Composer, and various Node.js package managers to manage PHP and frontend dependencies, build projects, and deploy the application.
+
+## Usage Example
+
+In this example, the `deploy` workflow is invoked with a custom Docker image, uses `npm` as the package manager, builds the frontend from the `frontend` directory, and passes customized Composer arguments. Secrets are provided for the SSH key and environment configuration.
+
+```yaml
+jobs:
+  deploy:
+    uses: your-repo/.github/workflows/deploy.yml@main
+    with:
+      image: your-custom-image
+      node-package-manager: npm
+      frontend-directory: frontend
+      composer-args: --no-dev
+    secrets:
+      ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+      env: ${{ secrets.ENV_CONTENT }}
+```
+
+### Secrets
+- **ssh-private-key** (required):
+    - **Type:** `string`
+    - **Description:** The SSH private key used to access the remote server for deployment. This is required for setting up SSH agent and making secure connections during the deployment process.
+
+- **env** (required):
+    - **Type:** `string`
+    - **Description:** The contents of the `.env` file, which is passed in as a secret.
+
+### Input Parameters
+- **image** (optional):
+    - **Type:** `string`
+    - **Default:** `git.qlic.nl/qlic/deploy:php8.3-node22`
+    - **Description:** The Docker image used for deployment, which can be overridden if necessary.
+
+- **node-package-manager** (optional):
+    - **Type:** `string`
+    - **Description:** The package manager to be used for the Node.js frontend build. Accepted values include `npm`, `yarn`, and `pnpm`.
+
+- **frontend-directory** (optional):
+    - **Type:** `string`
+    - **Description:** Directory where the frontend code is located, if applicable. Used when switching to the appropriate directory for Node.js builds.
+
+- **composer-args** (optional):
+    - **Type:** `string`
+    - **Default:**
+      ```bash
+      --verbose --prefer-dist --no-progress --no-interaction --no-dev --optimize-autoloader --ignore-platform-reqs
+      ```
+    - **Description:** Arguments passed to the Composer setup command for PHP dependency installation. These arguments can be customized based on specific requirements.
+
+- **username** (optional):
+    - **Type:** `string`
+    - **Default:** `${{ vars.REGISTRY_USERNAME }}`
+    - **Description:** Username for the Docker registry authentication. Defaults to the value stored in `vars.REGISTRY_USERNAME`.
+
+- **password** (optional):
+    - **Type:** `string`
+    - **Default:** `${{ vars.REGISTRY_PASSWORD }}`
+    - **Description:** Password for the Docker registry authentication. Defaults to the value stored in `vars.REGISTRY_PASSWORD`.
+
+## Workflow Job: `deploy`
+
+The `deploy` job handles the core deployment process. It consists of multiple steps to set up dependencies, manage environment variables, build frontend assets, configure SSH, and deploy the application.
+
+### Steps
+
+1. **Checkout Code:**
+    - **Action:** `actions/checkout@v4`
+    - **Description:** This step checks out the repository's code.
+
+2. **Setup Composer:**
+    - **Action:**  
+      Uses (`https://git.qlic.nl/actions/setup-composer@main`) to install PHP dependencies.
+    - **Inputs:**
+        - `args`: Composer arguments passed from the input `composer-args`.
+
+3. **Create `.env` File from Secret:**
+    - **Run Command:**
+      ```bash
+      echo "${{ secrets.env }}" > .env
+      ```
+    - **Description:** Writes the `.env` file using the secret passed through the `env` secret.
+
+4. **Build Frontend (Optional):**
+    - **Conditional Step:** Runs only if a `node-package-manager` is provided.
+    - **Run Commands:**
+        - If a `frontend-directory` is provided, it switches to that directory using `cd`.
+        - It installs dependencies using the provided Node.js package manager (e.g., `npm`, `yarn`, or `pnpm`).
+        - If a valid package manager is provided, it will also run the build command.
+    - **Description:** Handles the frontend build process by installing Node.js dependencies and running the build script, if applicable.
+
+5. **Set Up SSH Agent:**
+    - **Action:** `webfactory/ssh-agent@v0.5.3`
+    - **Description:** Sets up the SSH agent using the private key provided in the `ssh-private-key` secret. This is necessary for secure connections to the remote server during deployment.
+
+6. **Disable Strict Host Key Checking:**
+    - **Run Command:**
+      ```bash
+      echo "Host *" >> ~/.ssh/config
+      echo "    StrictHostKeyChecking no" >> ~/.ssh/config
+      ```
+    - **Description:** Disables strict host key checking for SSH, allowing connections to new or unknown hosts without requiring manual confirmation.
+
+7. **Deploy Application:**
+    - **Run Command:**
+      ```bash
+      vendor/bin/dep deploy environment=production
+      ```
+    - **Description:** Runs the deployment script using the `Deployer` tool, targeting the `production` environment.
+
+