From 5bc67f8d1877edcbe24e927209a1f1e0f5bce69f Mon Sep 17 00:00:00 2001 From: Jonathan Visser Date: Tue, 9 Dec 2025 19:20:07 +0100 Subject: [PATCH 1/2] refine the hypernode deploy documentation, rework Github Actions --- .../getting-started/configure-ci-cd.md | 124 ++++-------------- .../pipelines/bitbucket-pipelines.md | 12 +- .../pipelines/github-actions.md | 61 +++++---- docs/hypernode-deploy/pipelines/gitlab-ci.md | 10 ++ 4 files changed, 80 insertions(+), 127 deletions(-) diff --git a/docs/hypernode-deploy/getting-started/configure-ci-cd.md b/docs/hypernode-deploy/getting-started/configure-ci-cd.md index ef6329de..dbebb335 100644 --- a/docs/hypernode-deploy/getting-started/configure-ci-cd.md +++ b/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/ssh-agent@v0.9.1 - 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/ssh-agent@v0.9.1 - 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) diff --git a/docs/hypernode-deploy/pipelines/bitbucket-pipelines.md b/docs/hypernode-deploy/pipelines/bitbucket-pipelines.md index 9ea2bed3..10987bb1 100644 --- a/docs/hypernode-deploy/pipelines/bitbucket-pipelines.md +++ b/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. diff --git a/docs/hypernode-deploy/pipelines/github-actions.md b/docs/hypernode-deploy/pipelines/github-actions.md index f084ebb2..16f5288a 100644 --- a/docs/hypernode-deploy/pipelines/github-actions.md +++ b/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/ssh-agent@v0.7.0 - 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/ssh-agent@v0.7.0 - 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 + - 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/ssh-agent@v0.7.0 - 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. diff --git a/docs/hypernode-deploy/pipelines/gitlab-ci.md b/docs/hypernode-deploy/pipelines/gitlab-ci.md index c804a40c..ac247dff 100644 --- a/docs/hypernode-deploy/pipelines/gitlab-ci.md +++ b/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. From cd56b0a569af58bffe63ed782a450a301846a12f Mon Sep 17 00:00:00 2001 From: Jonathan Visser Date: Tue, 9 Dec 2025 19:24:51 +0100 Subject: [PATCH 2/2] Run formatter for whitespace trimming --- docs/hypernode-deploy/pipelines/github-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hypernode-deploy/pipelines/github-actions.md b/docs/hypernode-deploy/pipelines/github-actions.md index 16f5288a..74d97323 100644 --- a/docs/hypernode-deploy/pipelines/github-actions.md +++ b/docs/hypernode-deploy/pipelines/github-actions.md @@ -120,7 +120,7 @@ jobs: path: /tmp/composer-cache key: ${{ runner.os }}-composer - run: mkdir -p $HOME/.ssh - - run: hypernode-deploy deploy production -vvv # Deploy production stage defined in deploy.php + - run: hypernode-deploy deploy production -vvv # Deploy production stage defined in deploy.php env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} ```