Pipeline

This guide explains how to set up a GitLab pipeline for your Brezel instance. The pipeline will build and deploy your instance to one or multiple available deployment targets:

• An Ubuntu/Debian virtual server, using SSH
• Docker
• Kubernetes

Virtual Server using SSH

This section assumes you have access to a brezel user via SSH on a virtual server.

1. Generate an SSH keypair

On your local Linux/Unix machine, generate an RSA key pair:

ssh-keygen -b 4096 -C "example@GitLab"

This will output something like:

Generating public/private rsa key pair.
Enter file in which to save the key (/users/saul/.ssh/id_rsa):

Enter the path of the key. The name could be gitlab_rsa.

Enter passphrase (empty for no passphrase):

No passphrase. Hit enter.

Enter same passphrase again:

Hit enter. It will then output something like this:

Your identification has been saved in /users/saul/.ssh/gitlab_rsa.
Your public key has been saved in /users/saul/.ssh/gitlab_rsa.pub.
The key fingerprint is:
SHA256:hcsvjIXxM8ZS16X3IHIoGFwPSHr5Cjw35HOIZMEIW1c example@GitLab
The key's randomart image is:
+---[RSA 4096]----+
|...oo+Eoo     .  |
| o...oo+ + o o   |
|.   + * + * = o  |
|   + = X = o o o |
|    = O S       .|
|     + @ +       |
|      o o .      |
|         .       |
|                 |
+----[SHA256]-----+

Authorize the brezel user to access the virtual server via the private key. Login:

ssh brezel@brezel.example.io

Copy the contents of gitlab_rsa.pub and append it to ~/.ssh/authorized_keys:

echo "<PUBLIC KEY>" >> ~/.ssh/authorized_keys

2. Configure GitLab

In GitLab, go to the instance repository, to Settings > CI/CD > Variables and click on Add variable.

Key	Value	Protect variable
PRIVATE_KEY	Contents of your gitlab_rsa private key	✅
PROD_HOST	brezel.example.io	✅
PROD_PORT	22 (222 on Hetzner managed servers)	✅
PROD_USER	brezel	✅
PROD_PATH	/var/www/vhosts/brezel.example.io	✅
VITE_APP_API_URL	https://api.example.brezel.io	✅
VITE_APP_SYSTEM	example	✅

Make sure to add an empty newline at the end of PRIVATE_KEY!

Otherwise the pipline will fail as it pipes the value directly into a key file which needs a newline at the end.

Ensure that your pipelines can see the variables

They are protected by default, so either protect your branch as well or unprotect the variables (not recommended).

3. Configure your .gitlab-ci.yml

In your repository, there should be a .gitlab-ci.yml.example file. Create the .gitlab-ci.yml file:

cp .gitlab-ci.yml.example .gitlab-ci.yml

Add the file to git:

git add .gitlab-ci.yml

In your .gitlab-ci.yml, uncomment the SSH deployment line:

include:
# - local: 'gitlab/.Docker.gitlab-ci.yml'  # Uncomment this for Docker deployment
  - local: 'gitlab/.ssh.gitlab-ci.yml'     # Uncomment this for SSH deployment

Special case: Plesk

If your deployment target is a server managed by Plesk, then PHP is under a different path. Go to gitlab/.ssh.gitlab-ci.yml and change all occurrences of php in the script: sections to

/opt/plesk/php/7.4/bin/php ...

Keep in mind to also change the paths of composer. If you downloaded composer to ~/bin/composer, the lines should be

/opt/plesk/php/7.4/bin/php ~/bin/composer ...