Skip to content

Commit d6d0adc

Browse files
poespaspoespas
authored
Merge pull request #434 from ByteInternet/refine-hypernode-deploy-
Refine the hypernode deploy documentation, rework Github Actions
2 parents f5de346 + cd56b0a commit d6d0adc

File tree

4 files changed

+79
-126
lines changed

4 files changed

+79
-126
lines changed

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

Lines changed: 29 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,34 @@ There are many CI/CD pipelines available, but it's probably best to stick with t
1313

1414
In this example we'll be covering the Github Actions CI/CD configuration.
1515

16+
## How Hypernode Deploy pipelines work
17+
18+
Hypernode Deploy uses a **two-step architecture** designed to keep your server runtime fast and efficient:
19+
20+
### 1. Build step (runs in the CI/CD pipeline)
21+
22+
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:
23+
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.
24+
25+
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.
26+
27+
The build step produces a **build artifact** (typically `build.tgz`) containing your ready-to-deploy application.
28+
29+
### 2. Deploy step (runs in the CI/CD pipeline, deploys to server)
30+
31+
The deploy step also runs in your CI/CD pipeline infrastructure, but this time it:
32+
33+
- Downloads the build artifact created in the build step
34+
- Connects to your Hypernode server via SSH
35+
- Transfers the pre-built application to the server
36+
- Runs deployment tasks like:
37+
- Database migrations
38+
- Cache clearing
39+
- Symlink switching (zero-downtime deployments)
40+
- Running post-deployment hooks
41+
42+
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.
43+
1644
## Prepare the secrets
1745

1846
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
6896

6997
***Optional step***
7098

71-
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.
99+
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.
72100

73101
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**.
74102

75-
## Create the workflow file
76-
77-
Create the `.github/workflows` directory structure:
78-
79-
```console
80-
$ mkdir -p .github/workflows
81-
```
82-
83-
In that directory, create a file named `deploy.yaml` and fill in the following contents:
84-
85-
```yaml
86-
name: Build and deploy application
87-
88-
on:
89-
push:
90-
branches:
91-
- 'master' # Your main/master/production branch
92-
- 'staging' # Your staging/acceptance branch
93-
94-
run-name: Build and deploy application – ${{ github.ref_name }}
95-
```
96-
97-
### Build step
98-
99-
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.
100-
101-
```yaml
102-
env:
103-
COMPOSER_CACHE_DIR: /tmp/composer-cache
104-
105-
jobs:
106-
build:
107-
runs-on: ubuntu-latest
108-
timeout-minutes: 60
109-
# Here we use the latest Hypernode Deploy image with PHP 8.4 and Node.js 22
110-
container: quay.io/hypernode/deploy:latest-php8.4-node22
111-
steps:
112-
- uses: actions/checkout@v5
113-
- uses: actions/cache@v4
114-
with:
115-
path: /tmp/composer-cache
116-
key: ${{ runner.os }}-composer
117-
- uses: webfactory/ssh-agent@v0.9.1
118-
with:
119-
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
120-
- run: hypernode-deploy build -vvv
121-
env:
122-
DEPLOY_COMPOSER_AUTH: ${{ secrets.DEPLOY_COMPOSER_AUTH }}
123-
- name: archive production artifacts
124-
uses: actions/upload-artifact@v4
125-
with:
126-
name: deployment-build
127-
path: build/build.tgz
128-
retention-days: 1
129-
```
130-
131-
### Deploy step
132-
133-
For the deployment part, add a job called `deploy` to the `jobs` configuration.
134-
135-
```yaml
136-
...
137-
138-
jobs:
139-
build:
140-
...
141-
deploy:
142-
needs: build
143-
runs-on: ubuntu-latest
144-
timeout-minutes: 60
145-
# Here we use the latest Hypernode Deploy image with PHP 8.4 and Node.js 22
146-
container: quay.io/hypernode/deploy:latest-php8.4-node22
147-
steps:
148-
- uses: actions/checkout@v5
149-
- name: download build artifact
150-
uses: actions/download-artifact@v5
151-
with:
152-
name: deployment-build
153-
path: build/
154-
- uses: webfactory/ssh-agent@v0.9.1
155-
with:
156-
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
157-
- run: mkdir -p $HOME/.ssh
158-
- name: deploy to staging # Staging deployment happens here
159-
if: github.ref == 'refs/heads/staging'
160-
run: hypernode-deploy deploy staging -vvv
161-
- name: deploy to production # Production deployment happens here
162-
if: github.ref == 'refs/heads/master'
163-
run: hypernode-deploy deploy production -vvv
164-
- name: cleanup acquired resources
165-
if: ${{ always() }}
166-
run: hypernode-deploy cleanup
167-
```
168-
169103
```{note}
170104
CI/CD configuration templates can be found here:
171105
- [Github Actions](../pipelines/github-actions.md)

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

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Bitbucket Pipelines
22

3+
```{note}
4+
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.
5+
```
6+
37
## Configuring deployment environments
48

59
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
2327

2428
#### Generating own pair of SSH Keys
2529

26-
You cangenerate an SSH keypair on the server, copy the public key to the `~/.ssh/authorized_keys` file
30+
You can generate an SSH keypair on the server, copy the public key to the `~/.ssh/authorized_keys` file
2731
and encode the private key with base64. We'll use this base64-encoded private key later on.
2832

2933
```console
@@ -110,3 +114,9 @@ pipelines:
110114
script:
111115
- hypernode-deploy deploy staging
112116
```
117+
118+
## Next steps
119+
120+
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`.
121+
122+
Once pushed, you will see a Pipeline automatically run in your repository's "Pipelines" tab.

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

Lines changed: 29 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,15 @@
11
# GitHub Actions
22

3-
## Configuring deployment environments
4-
5-
To start using GitHub Actions, we need to prepare the environments we want to deploy to.
6-
7-
For example, these environments can be:
8-
9-
- production
10-
- acceptance (or staging)
11-
- test
3+
```{note}
4+
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.
5+
```
126

13-
### Configuring the production environment
7+
## Configuring SSH authentication
148

159
Hypernode Deploy will need a pair of SSH keys for authentication to the server.
1610

17-
First, we generate an SSH keypair on the production server, copy the public key to the `~/.ssh/authorized_keys` file
18-
and encode the private key with base64. We'll use this base64-encoded private key later on.
11+
First, we generate an SSH keypair on one of your servers (e.g., production), copy the public key to the `~/.ssh/authorized_keys` file
12+
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.
1913

2014
```console
2115
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
2418
LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
2519
```
2620

27-
Now go to your GitHub project and go to **Settings -> Environments**.
21+
```{note}
22+
If you have multiple environments (production, acceptance, staging), make sure to add the public key to each server through the Control Panel.
23+
```
24+
25+
Now go to your GitHub project and go to **Settings -> Secrets and variables -> Actions**.
2826

29-
1. Create a new environment called `production`, if it doesn't exist yet.
30-
1. Click the `production` environment and click `Add secret`.
27+
1. Click **New repository secret**.
3128
1. Set the **Name** to `SSH_PRIVATE_KEY`.
3229
1. Set the **Value** to the base64-encoded private key we generated earlier.
3330
1. Click **Add secret**.
3431

35-
### Configuring the acceptance environment
36-
37-
If you have an acceptance (or staging) environment, repeat the same steps for the production environment, but now for
38-
your acceptance environment, with the GitHub environment name `acceptance`.
39-
4032
## Build
4133

4234
To get started, we need to make sure the `.github/workflows` directory structure exists.
@@ -65,10 +57,10 @@ jobs:
6557
with:
6658
path: /tmp/composer-cache
6759
key: ${{ runner.os }}-composer
68-
- uses: webfactory/ssh-agent@v0.7.0
69-
with:
70-
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
60+
- run: mkdir -p $HOME/.ssh
7161
- run: hypernode-deploy build -vvv
62+
env:
63+
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
7264
- name: archive production artifacts
7365
uses: actions/upload-artifact@v4
7466
with:
@@ -98,11 +90,13 @@ name: Deploy application to production
9890
on:
9991
push:
10092
branches:
101-
- 'master' # production branch
93+
- 'master'
94+
- 'main'
10295
10396
jobs:
10497
build:
10598
uses: ./.github/workflows/build.yml
99+
secrets: inherit
106100
107101
deploy:
108102
needs: build
@@ -125,11 +119,10 @@ jobs:
125119
with:
126120
path: /tmp/composer-cache
127121
key: ${{ runner.os }}-composer
128-
- uses: webfactory/ssh-agent@v0.7.0
129-
with:
130-
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
131122
- run: mkdir -p $HOME/.ssh
132123
- run: hypernode-deploy deploy production -vvv # Deploy production stage defined in deploy.php
124+
env:
125+
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
133126
```
134127
135128
## Deploy to acceptance
@@ -147,6 +140,7 @@ on:
147140
jobs:
148141
build:
149142
uses: ./.github/workflows/build.yml
143+
secrets: inherit
150144
151145
deploy:
152146
needs: build
@@ -169,9 +163,14 @@ jobs:
169163
with:
170164
path: /tmp/composer-cache
171165
key: ${{ runner.os }}-composer
172-
- uses: webfactory/ssh-agent@v0.7.0
173-
with:
174-
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
175166
- run: mkdir -p $HOME/.ssh
176167
- run: hypernode-deploy deploy acceptance -vvv # Deploy acceptance/staging stage defined in deploy.php
168+
env:
169+
SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
177170
```
171+
172+
## Next steps
173+
174+
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`.
175+
176+
Once pushed, you will see a GitHub Action automatically run in your repository's "Actions" tab.

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Gitlab CI
22

3+
```{note}
4+
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.
5+
```
6+
37
## Configuring deployment environments
48

59
To start using Gitlab CI, we need to prepare the environments we want to deploy to.
@@ -109,3 +113,9 @@ deploy_acceptance:
109113
name: acceptance
110114
url: https://acceptance.example.com
111115
```
116+
117+
## Next steps
118+
119+
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`.
120+
121+
Once pushed, you will see a Pipeline automatically run in your repository's "Build" -> "Pipelines" or "CI/CD" -> "Pipelines" tab.

0 commit comments

Comments
 (0)