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 (recommended)

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

Kubernetes Deployment with Terraform (default)

This section explains how to deploy the Brezel instance to a Kubernetes cluster using Terraform.

Prerequisites

Before you begin, ensure you have the following:

1. You have pushed the package-lock.json and composer.lock files to your repository. This is important for the pipeline to work correctly.
2. A Kubernetes cluster with sufficient resources
3. A Scaleway account (if you’re using Scaleway as your cloud provider)
4. Required environment variables or secrets for your Brezel instance

Terraform Configuration

The project includes Terraform configurations in the terraform directory. These configurations use the brezel-instance/kubernetes//brezel-instance module to deploy Brezel to a Kubernetes cluster. The deployed Brezel instance will be available under

• {branch_slug}.{system}.{base_domain} for the web application
• api.{branch_slug}.{system}.{base_domain} for the API
• brotcast.{branch_slug}.{system}.{base_domain} for the Brotcast service
• pma.{branch_slug}.{system}.{base_domain} for PhpMyAdmin (if enabled)

E.g., for the system “acme” in the Git branch “staging” and the base domain “review.brezel.cloud”, the URLs would be:

• staging.acme.review.brezel.cloud for the web application
• api.staging.acme.review.brezel.cloud for the API
• brotcast.staging.acme.review.brezel.cloud for the Brotcast service
• pma.staging.acme.review.brezel.cloud for PhpMyAdmin (if enabled)

The Docker images will be pulled from

• {registry_image}:{branch_slug}

Key Files

• gitlab-ci.yml: The GitLab CI/CD configuration file
• main.tf: Contains the main Terraform configuration for deploying Brezel
• variables.tf: Defines the variables used in the Terraform configuration
• backend.tf: Configures the Terraform backend for state storage
• scaleway.auto.tfvars: Contains variables specific to Scaleway (if you’re using Scaleway)

Deployment Steps

1. Build and Push Docker Images

In your .gitlab-ci.yml, uncomment the Terraform deployment section in the .gitlab-ci.yml file so that it looks like this:

include:
  - local: 'gitlab/.terraform.gitlab-ci.yml'

variables:
  SYSTEM: "example"  # Replace it with your system name

2. Configure Variables

You can configure variables in the GitLab CI/CD settings for your project (Settings > CI/CD > Variables).

Required variables:

• TF_VAR_vapid_public_key: The VAPID public key used for push notifications.
• TF_VAR_vapid_private_key: The VAPID private key used for push notifications.

You must generate them locally via php bakery init, copy them from your .env file, and copy them to the GitLab CI/CD variables.

Optional variables:

• TF_VAR_namespace: Override the namespace for the Kubernetes resources. If not set, it will be generated using the review template review-{system}-{branch_slug}.
• TF_VAR_host: Override the base hostname for the application. If not set, it will be generated using the review template {branch_slug}.{system}.{base_domain}.
• TF_VAR_registry_image: The container registry URL where the Docker images are stored. This is filled automatically by the GitLab pipeline.
• TF_VAR_base_domain: The base domain for the application. Projects under https://gitlab.kiwis-and-brownies.de/kibro/basedonbrezel/ have this set automatically.
• TF_VAR_scw_rdb_instance_id: The Scaleway RDB instance ID for the database. Projects under https://gitlab.kiwis-and-brownies.de/kibro/basedonbrezel/ have this set automatically.
• TF_VAR_app_env: The environment (e.g., production, staging). Default is staging.
• TF_VAR_secure: Whether to issue a certificate for the domain. Default is true.
• TF_VAR_mail_host: The SMTP server used for sending emails.
• TF_VAR_mail_port: The SMTP server port.
• TF_VAR_mail_username: The SMTP username.
• TF_VAR_mail_password: The SMTP password.
• TF_VAR_mail_encryption: The encryption method used for the SMTP server (e.g., ssl, tls). Default is tls.
• TF_VAR_mail_from_address: The email address used for sending emails.
• TF_VAR_mail_from_name: The name used for sending emails.
• TF_VAR_vapid_public_key: The VAPID public key used for push notifications.
• TF_VAR_vapid_private_key: The VAPID private key used for push notifications.

You can also set these in variable files (e.g., terraform.tfvars or scaleway.auto.tfvars), where you don’t need to set the TF_VAR_ prefix for variable names.

Tip

In production, you typically don’t want a hostname like main.example.review.brezel.cloud. In the GitLab CI/CD settings, configure these variables to apply to your specific production environment:

• TF_VAR_host: example.com
• TF_VAR_namespace: example

Deployment from Local Machine

3. Initialize Terraform

Set required environment variables for initialization. You can do this in your shell or in a .env file under the terraform directory. The required variables for Terraform initialization are:

• GITLAB_USERNAME: GitLab username
• GITLAB_ACCESS_TOKEN: GitLab password or personal access token

Then, navigate to the terraform directory and initialize Terraform:

cd terraform
./init.sh  # or terraform init if you're not using the provided script

4. Plan the Deployment

Generate and review the Terraform execution plan:

terraform plan -out=tfplan

5. Apply the Configuration

Apply the Terraform configuration to create or update the infrastructure:

terraform apply tfplan