Refine the hypernode deploy documentation, rework Github Actions

docs/hypernode-deploy/getting-started/configure-ci-cd.md

@@ -13,6 +13,34 @@ There are many CI/CD pipelines available, but it's probably best to stick with t
 
 In this example we'll be covering the Github Actions CI/CD configuration.
 
+## How Hypernode Deploy pipelines work
+
+Hypernode Deploy uses a **two-step architecture** designed to keep your server runtime fast and efficient:
+
+### 1. Build step (runs in the CI/CD pipeline)
+
+The build step runs entirely within your CI/CD pipeline's infrastructure (GitHub Actions, GitLab CI, or Bitbucket Pipelines) and **never touches your production server**. This is where all the heavy, resource-intensive work happens:
+The build step handles all resource-intensive operations: installing dependencies with `composer install`, compiling frontend assets and themes, running code minification and image optimization, and performing any other heavy preparation tasks needed to ready your application for deployment.
+
+By performing these heavy operations in the pipeline, you avoid consuming precious server resources. Your production server stays responsive and dedicated to serving customer requests, not compiling code or building assets.
+
+The build step produces a **build artifact** (typically `build.tgz`) containing your ready-to-deploy application.
+
+### 2. Deploy step (runs in the CI/CD pipeline, deploys to server)
+
+The deploy step also runs in your CI/CD pipeline infrastructure, but this time it:
+
+- Downloads the build artifact created in the build step
+- Connects to your Hypernode server via SSH
+- Transfers the pre-built application to the server
+- Runs deployment tasks like:
+  - Database migrations
+  - Cache clearing
+  - Symlink switching (zero-downtime deployments)
+  - Running post-deployment hooks
+
+This way your artifact deploys in seconds, seserver resources stay focused on serving customers, and you can deploy the same tested build to multiple environments without rebuilding.
+
 ## Prepare the secrets
 
 Hypernode Deploy needs a few 'credentials' to be able to function. The necessary credentials are:
@@ -68,104 +96,10 @@ Then go to your Github repository on Github.com and go to **Settings -> Secrets
 
 ***Optional step***
 
-We assume you want to use the Hypernode Brancher feature to spin up temporary nodes based on a specific Hypernode. SSH into that Hypernode and copy the contents of the `/etc/hypernode/hypernode_api_token` file.
+We assume you may want to use the Hypernode Brancher feature to spin up temporary nodes based on a specific Hypernode. SSH into that Hypernode and copy the contents of the `/etc/hypernode/hypernode_api_token` file.
 
 Then go to your Github repository on Github.com and go to **Settings -> Secrets -> Actions**. Click the **New repository secret**, fill in `HYPERNODE_API_TOKEN` as the name, paste the contents of your `hypernode_api_token` file and press **Save**.
 
-## Create the workflow file
-
-Create the `.github/workflows` directory structure:
-
-```console
-$ mkdir -p .github/workflows
-```
-
-In that directory, create a file named `deploy.yaml` and fill in the following contents:
-
-```yaml
-name: Build and deploy application
-
-on:
-  push:
-    branches:
-      - 'master'  # Your main/master/production branch
-      - 'staging' # Your staging/acceptance branch
-
-run-name: Build and deploy application – ${{ github.ref_name }}
-```
-
-### Build step
-
-The first thing we want to run is the `build` step, which does all the dirty work to prepare the application for the web. Add the following configuration to the `deploy.yaml` file.
-
-```yaml
-env:
-  COMPOSER_CACHE_DIR: /tmp/composer-cache
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    # Here we use the latest Hypernode Deploy image with PHP 8.4 and Node.js 22
-    container: quay.io/hypernode/deploy:latest-php8.4-node22
-    steps:
-      - uses: actions/checkout@v5
-      - uses: actions/cache@v4
-        with:
-          path: /tmp/composer-cache
-          key: ${{ runner.os }}-composer
-      - uses: webfactory/[email protected]
-        with:
-          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
-      - run: hypernode-deploy build -vvv
-        env:
-          DEPLOY_COMPOSER_AUTH: ${{ secrets.DEPLOY_COMPOSER_AUTH }}
-      - name: archive production artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: deployment-build
-          path: build/build.tgz
-          retention-days: 1
-```
-
-### Deploy step
-
-For the deployment part, add a job called `deploy` to the `jobs` configuration.
-
-```yaml
-...
-
-jobs:
-  build:
-    ...
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    # Here we use the latest Hypernode Deploy image with PHP 8.4 and Node.js 22
-    container: quay.io/hypernode/deploy:latest-php8.4-node22
-    steps:
-      - uses: actions/checkout@v5
-      - name: download build artifact
-        uses: actions/download-artifact@v5
-        with:
-          name: deployment-build
-          path: build/
-      - uses: webfactory/[email protected]
-        with:
-          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
-      - run: mkdir -p $HOME/.ssh
-      - name: deploy to staging     # Staging deployment happens here
-        if: github.ref == 'refs/heads/staging'
-        run: hypernode-deploy deploy staging -vvv
-      - name: deploy to production  # Production deployment happens here
-        if: github.ref == 'refs/heads/master'
-        run: hypernode-deploy deploy production -vvv
-      - name: cleanup acquired resources
-        if: ${{ always() }}
-        run: hypernode-deploy cleanup
-```
-
 ```{note}
 CI/CD configuration templates can be found here:
 - [Github Actions](../pipelines/github-actions.md)

docs/hypernode-deploy/pipelines/bitbucket-pipelines.md

@@ -1,5 +1,9 @@
 # Bitbucket Pipelines
 
+```{note}
+This guide assumes you have already configured Hypernode Deploy with a `deploy.php` file in your project root. If you haven't set this up yet, please follow the [installation and configuration guide](../getting-started/install-and-configure-hypernode-deploy.md) first.
+```
+
 ## Configuring deployment environments
 
 To start using Bitbucket Pipelines, we need to prepare the environments we want to deploy to.
@@ -23,7 +27,7 @@ Bitbucket allows you to create an SSH key from the Repository Settings, you do t
 
 #### Generating own pair of SSH Keys
 
-You cangenerate an SSH keypair on the server, copy the public key to the `~/.ssh/authorized_keys` file
+You can generate an SSH keypair on the server, copy the public key to the `~/.ssh/authorized_keys` file
 and encode the private key with base64. We'll use this base64-encoded private key later on.
 
 ```console
@@ -110,3 +114,9 @@ pipelines:
         script:
           - hypernode-deploy deploy staging
 ```
+
+## Next steps
+
+After you've added these files, commit your changes and make sure the changes are newly present on the branches configured in your pipeline files. By default, these branches are `master` (or `main`) and `acceptance`.
+
+Once pushed, you will see a Pipeline automatically run in your repository's "Pipelines" tab.

docs/hypernode-deploy/pipelines/github-actions.md

@@ -1,21 +1,15 @@
 # GitHub Actions
 
-## Configuring deployment environments
-
-To start using GitHub Actions, we need to prepare the environments we want to deploy to.
-
-For example, these environments can be:
-
-- production
-- acceptance (or staging)
-- test
+```{note}
+This guide assumes you have already configured Hypernode Deploy with a `deploy.php` file in your project root. If you haven't set this up yet, please follow the [installation and configuration guide](../getting-started/install-and-configure-hypernode-deploy.md) first.
+```
 
-### Configuring the production environment
+## Configuring SSH authentication
 
 Hypernode Deploy will need a pair of SSH keys for authentication to the server.
 
-First, we generate an SSH keypair on the production server, copy the public key to the `~/.ssh/authorized_keys` file
-and encode the private key with base64. We'll use this base64-encoded private key later on.
+First, we generate an SSH keypair on one of your servers (e.g., production), copy the public key to the `~/.ssh/authorized_keys` file
+on all servers you want to deploy to, and encode the private key with base64. We'll use this base64-encoded private key later on.
 
 ```console
 app@abc-example-magweb-cmbl:~$ ssh-keygen -t ed25519 -C gh-actions-deploy -f gh-actions-deploy -q -P ""
@@ -24,19 +18,17 @@ app@abc-example-magweb-cmbl:~$ cat gh-actions-deploy | base64 -w0  # encode the
 LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
 ```
 
-Now go to your GitHub project and go to **Settings -> Environments**.
+```{note}
+If you have multiple environments (production, acceptance, staging), make sure to add the public key to each server through the Control Panel.
+```
+
+Now go to your GitHub project and go to **Settings -> Secrets and variables -> Actions**.
 
-1. Create a new environment called `production`, if it doesn't exist yet.
-1. Click the `production` environment and click `Add secret`.
+1. Click **New repository secret**.
 1. Set the **Name** to `SSH_PRIVATE_KEY`.
 1. Set the **Value** to the base64-encoded private key we generated earlier.
 1. Click **Add secret**.
 
-### Configuring the acceptance environment
-
-If you have an acceptance (or staging) environment, repeat the same steps for the production environment, but now for
-your acceptance environment, with the GitHub environment name `acceptance`.
-
 ## Build
 
 To get started, we need to make sure the `.github/workflows` directory structure exists.
@@ -65,10 +57,10 @@ jobs:
       with:
         path: /tmp/composer-cache
         key: ${{ runner.os }}-composer
-    - uses: webfactory/[email protected]
-      with:
-        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
+    - run: mkdir -p $HOME/.ssh
     - run: hypernode-deploy build -vvv
+      env:
+        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
     - name: archive production artifacts
       uses: actions/upload-artifact@v4
       with:
@@ -98,11 +90,13 @@ name: Deploy application to production
 on:
   push:
     branches:
-      - 'master'  # production branch
+      - 'master'
+      - 'main'
 
 jobs:
   build:
     uses: ./.github/workflows/build.yml
+    secrets: inherit
 
   deploy:
     needs: build
@@ -125,11 +119,10 @@ jobs:
       with:
         path: /tmp/composer-cache
         key: ${{ runner.os }}-composer
-    - uses: webfactory/[email protected]
-      with:
-        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
     - run: mkdir -p $HOME/.ssh
     - run: hypernode-deploy deploy production -vvv  # Deploy production stage defined in deploy.php
+      env:
+        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
 ```
 
 ## Deploy to acceptance
@@ -147,6 +140,7 @@ on:
 jobs:
   build:
     uses: ./.github/workflows/build.yml
+    secrets: inherit
 
   deploy:
     needs: build
@@ -169,9 +163,14 @@ jobs:
       with:
         path: /tmp/composer-cache
         key: ${{ runner.os }}-composer
-    - uses: webfactory/[email protected]
-      with:
-        ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
     - run: mkdir -p $HOME/.ssh
     - run: hypernode-deploy deploy acceptance -vvv  # Deploy acceptance/staging stage defined in deploy.php
+      env:
+        SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
 ```
+
+## Next steps
+
+After you've added these files, commit your changes and make sure the changes are newly present on the branches configured in your pipeline files. By default, these branches are `master` (or `main`) and `acceptance`.
+
+Once pushed, you will see a GitHub Action automatically run in your repository's "Actions" tab.

docs/hypernode-deploy/pipelines/gitlab-ci.md

@@ -1,5 +1,9 @@
 # Gitlab CI
 
+```{note}
+This guide assumes you have already configured Hypernode Deploy with a `deploy.php` file in your project root. If you haven't set this up yet, please follow the [installation and configuration guide](../getting-started/install-and-configure-hypernode-deploy.md) first.
+```
+
 ## Configuring deployment environments
 
 To start using Gitlab CI, we need to prepare the environments we want to deploy to.
@@ -109,3 +113,9 @@ deploy_acceptance:
     name: acceptance
     url: https://acceptance.example.com
 ```
+
+## Next steps
+
+After you've added these files, commit your changes and make sure the changes are newly present on the branches configured in your pipeline files. By default, these branches are `master` (or `main`) and `acceptance`.
+
+Once pushed, you will see a Pipeline automatically run in your repository's "Build" -> "Pipelines" or "CI/CD" -> "Pipelines" tab.