Skip to content

Commit 5da1088

Browse files
tdgroottdgroot
committed
docs: Add docs for GitHub Actions and Gitlab CI
1 parent 77dde68 commit 5da1088

File tree

4 files changed

+276
-5
lines changed

4 files changed

+276
-5
lines changed

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

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

3-
TODO
3+
This article is currently work in progress!

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

Lines changed: 164 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,165 @@
1-
# Github Actions
1+
# GitHub Actions
22

3-
TODO
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
12+
13+
### Configuring the production environment
14+
15+
Hypernode Deploy will need a pair of SSH keys for authentication to the server.
16+
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.
19+
20+
```console
21+
app@abc-example-magweb-cmbl:~$ ssh-keygen -t ed25519 -C gh-actions-deploy -f gh-actions-deploy -q -P ""
22+
app@abc-example-magweb-cmbl:~$ cat gh-actions-deploy.pub >> ~/.ssh/authorized_keys
23+
app@abc-example-magweb-cmbl:~$ cat gh-actions-deploy | base64 -w0 # encode the private key with base64
24+
LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
25+
```
26+
27+
Now go to your GitHub project and go to **Settings -> Environments**.
28+
29+
1. Create a new environment called `production`, if it doesn't exist yet.
30+
1. Click the `production` environment and click `Add secret`.
31+
1. Set the name of the secret to `SSH_PRIVATE_KEY`.
32+
1. Set the value of the secret to the base64-encoded private key we generated earlier.
33+
1. Click **Add secret**.
34+
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+
40+
## Build
41+
42+
To get started, we need to make sure the `.github/workflows` directory structure exists.
43+
44+
```bash
45+
mkdir -p .github/workflows
46+
```
47+
48+
Then create the file `.github/workflows/build.yml` with the contents below.
49+
This workflow will be used in other workflows.
50+
51+
```yaml
52+
name: Build application
53+
54+
on:
55+
workflow_call:
56+
57+
jobs:
58+
build:
59+
runs-on: ubuntu-latest
60+
container: quay.io/hypernode/deploy:3-php8.1-node18
61+
steps:
62+
- uses: actions/checkout@v3
63+
- uses: actions/cache@v3
64+
with:
65+
path: /tmp/composer-cache
66+
key: ${{ runner.os }}-composer
67+
- uses: webfactory/ssh-agent@v0.7.0
68+
with:
69+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
70+
- run: hypernode-deploy build -vvv
71+
- name: archive production artifacts
72+
uses: actions/upload-artifact@v3
73+
with:
74+
name: deployment-build
75+
path: build/build.tgz
76+
retention-days: 7
77+
```
78+
79+
## Deploy to production
80+
81+
Create a file called `.github/workflows/deploy_production.yml` with the following contents.
82+
83+
```yaml
84+
name: Deploy application to production
85+
86+
on:
87+
push:
88+
branches:
89+
- 'master' # production branch
90+
91+
jobs:
92+
build:
93+
uses: ./.github/workflows/build.yml
94+
95+
deploy:
96+
needs: build
97+
runs-on: ubuntu-latest
98+
# Concurrency takes any arbitrary value, but this prevents multiple deployments happening at the same time.
99+
# We set the concurrency to production for this deployment workflow.
100+
concurrency: production
101+
environment:
102+
name: production
103+
url: https://www.example.com
104+
container: quay.io/hypernode/deploy:3-php8.1-node18
105+
steps:
106+
- uses: actions/checkout@v3
107+
- name: download build artifact
108+
uses: actions/download-artifact@v3
109+
with:
110+
name: deployment-build
111+
path: build/
112+
- uses: actions/cache@v3
113+
with:
114+
path: /tmp/composer-cache
115+
key: ${{ runner.os }}-composer
116+
- uses: webfactory/ssh-agent@v0.7.0
117+
with:
118+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
119+
- run: mkdir -p $HOME/.ssh
120+
- run: hypernode-deploy deploy production -vvv # Deploy production stage defined in deploy.php
121+
```
122+
123+
## Deploy to acceptance
124+
125+
Create a file called `.github/workflows/deploy_acceptance.yml` with the following contents.
126+
127+
```yaml
128+
name: Deploy application to acceptance
129+
130+
on:
131+
push:
132+
branches:
133+
- 'acceptance' # acceptance/staging branch
134+
135+
jobs:
136+
build:
137+
uses: ./.github/workflows/build.yml
138+
139+
deploy:
140+
needs: build
141+
runs-on: ubuntu-latest
142+
# Concurrency takes any arbitrary value, but this prevents multiple deployments happening at the same time.
143+
# We set the concurrency to acceptance for this deployment workflow.
144+
concurrency: acceptance
145+
environment:
146+
name: acceptance
147+
url: https://acceptance.example.com
148+
container: quay.io/hypernode/deploy:3-php8.1-node18
149+
steps:
150+
- uses: actions/checkout@v3
151+
- name: download build artifact
152+
uses: actions/download-artifact@v3
153+
with:
154+
name: deployment-build
155+
path: build/
156+
- uses: actions/cache@v3
157+
with:
158+
path: /tmp/composer-cache
159+
key: ${{ runner.os }}-composer
160+
- uses: webfactory/ssh-agent@v0.7.0
161+
with:
162+
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
163+
- run: mkdir -p $HOME/.ssh
164+
- run: hypernode-deploy deploy acceptance -vvv # Deploy acceptance/staging stage defined in deploy.php
165+
```

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

Lines changed: 108 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,110 @@
11
# Gitlab CI
22

3-
TODO
3+
## Configuring deployment environments
4+
5+
To start using Gitlab CI, 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
12+
13+
### Configuring the production environment
14+
15+
Hypernode Deploy will need a pair of SSH keys for authentication to the server.
16+
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.
19+
20+
```console
21+
app@abc-example-magweb-cmbl:~$ ssh-keygen -t ed25519 -C gitlab-ci-deploy -f gitlab-ci-deploy -q -P ""
22+
app@abc-example-magweb-cmbl:~$ cat gitlab-ci-deploy.pub >> ~/.ssh/authorized_keys
23+
app@abc-example-magweb-cmbl:~$ cat gitlab-ci-deploy | base64 -w0 # encode the private key with base64
24+
LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0KYjNCbGJuTnphQzFyWlhrdGRqRUFBQUFBQkc1dmJtV...
25+
```
26+
27+
Now go to your Gitlab project and go to **Deployments -> Environments**.
28+
29+
1. Create a new environment called `production`, if it doesn't exist yet.
30+
1. Go to **Settings -> CI/CD -> Variables**.
31+
1. Click `Add variables`.
32+
1. Set **Key** to `SSH_PRIVATE_KEY`.
33+
1. Set **Value** to the base64-encoded private key we generated earlier.
34+
1. Set **Environment scope** to `production`.
35+
1. If you don't have protected branches configured, uncheck the setting **Protect variable**.
36+
1. Check the setting **Mask variable**.
37+
1. Click **Add variable**.
38+
39+
### Configuring the acceptance environment
40+
41+
If you have an acceptance (or staging) environment, repeat the same steps for the production environment, but now for
42+
your acceptance environment, with the Gitlab environment name `acceptance`.
43+
44+
## Build
45+
46+
Create a file called `.gitlab-ci.yml` with the contents below.
47+
48+
This sets the container image, defines the CI/CD stages and defines the build step (part of the build stage).
49+
50+
```yaml
51+
# See https://quay.io/repository/hypernode/deploy?tab=tags for all possible tags.
52+
image: quay.io/hypernode/deploy:3-php8.1-node18
53+
54+
stages:
55+
- build
56+
- deploy
57+
58+
build:
59+
stage: build
60+
only:
61+
- merge_requests
62+
- acceptance
63+
- master
64+
script:
65+
- hypernode-deploy build -vvv
66+
artifacts:
67+
paths:
68+
- build/**
69+
```
70+
71+
Don't forget to set the specifications of the image to what your project needs,
72+
so if for example your project needs PHP 7.4 and Node.js 16, set the image to:
73+
74+
```yaml
75+
image: quay.io/hypernode/deploy:3-php7.4-node16
76+
```
77+
78+
## Deploy to production
79+
80+
Add the following to the `.gitlab-ci.yml` file.
81+
82+
```yaml
83+
# Deploy to production
84+
deploy_production:
85+
stage: deploy
86+
only:
87+
- master # production branch
88+
script:
89+
- hypernode-deploy deploy production
90+
environment:
91+
name: production
92+
url: https://www.example.com
93+
```
94+
95+
## Deploy to acceptance
96+
97+
If you have an acceptance (or staging) stage in your deployment flow, here's an example on how to deploy that.
98+
99+
```yaml
100+
# Deploy to acceptance
101+
deploy_acceptance:
102+
stage: deploy
103+
only:
104+
- acceptance # acceptance/staging branch
105+
script:
106+
- hypernode-deploy deploy acceptance
107+
environment:
108+
name: acceptance
109+
url: https://acceptance.example.com
110+
```

‎docs/hypernode-platform/nginx/how-to-configure-nginx-for-a-multistore.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ set $storecode "example_storecode";
3737
```
3838

3939
```{note}
40-
If you have a multistore, with hypernode-manage-vhost enabled AND you are using Varnish. You'd have to prefix the file with `varnish` instead of `server`, like `varnish.storecode`. This way these multistore requests will go through varnish and will then be rewritten accordingly with the `varnish.storecode` configuration.
40+
If you have a multistore, with hypernode-manage-vhost enabled AND you are using Varnish.
41+
You'd have to prefix the file with `varnish` instead of `server`, like `varnish.storecode`.
42+
This way these multistore requests will go through varnish and will then be rewritten accordingly with the `varnish.storecode` configuration.
4143
```
4244

4345
### Using Subdirectories

0 commit comments

Comments
 (0)