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!

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 ...