Virtual Server

  6 minute read  

This guide explains how to deploy a Brezel instance to a (virtual) server. For this guide, we assume the base domain is called example.io and Brezel will be accessible under brezel.example.io. The example IP of the server is given as 5.35.243.342.

Prerequisites

  • Root access
  • Ubuntu or Debian
  • Nginx
  • GitLab repository for your Brezel instance

0. Install Nginx, PHP, MySQL/MariaDB and Certbot

apt-get update
apt-get install nginx certbot python3-certbot-nginx php7.4-fpm php7.4-curl php7.4-gd php7.4-xml php7.4-zip php7.4-mysql

Install MariaDB using a guide like this .

1. Add DNS records

Login to your external DNS provider and add the following DNS records (replace the bold values with your use case):

NameTypeValue
brezel.example.ioA5.35.243.342
*.brezel.example.ioA5.35.243.342

2. Add the SPA domain

In /etc/nginx/sites-available, create a new file called spa:

server {
    listen 80;
    listen [::]:80;
	server_name brezel.example.io;

    location / {
	    root /var/www/vhosts/api.brezel.example.io/dist;
        index  index.html index.htm;
        try_files $uri $uri/ /index.html;
    }

    # redirect server error pages to the static page /50x.html
    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
	    root /var/www/vhosts/api.brezel.example.io/dist;
    }
}

Save the file, then create a symlink:

ln -s /etc/nginx/sites-available/spa /etc/nginx/sites-enabled/spa

Restart NGINX:

systemctl restart nginx

Secure the SPA domain

sudo certbot --nginx -d brezel.example.io

3. Add the API domain

In /etc/nginx/sites-available, create a new file called api:

server {
    listen 80;
    listen [::]:80;
	server_name api.brezel.example.io;
    
	# SSL configuration
	#
	#listen 443 ssl default_server;
	#listen [::]:443 ssl default_server;
	#
	# Note: You should disable gzip for SSL traffic.
	# See: https://bugs.debian.org/773332
	#
	# Read up on ssl_ciphers to ensure a secure configuration.
	# See: https://bugs.debian.org/765782
	#
	# Self signed certs generated by the ssl-cert package
	# Don't use them in a production server!
	#
	# include snippets/snakeoil.conf;

	root /var/www/vhosts/api.brezel.example.io/public;

	add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

	# Add index.php to the list if you are using PHP
	index index.php index.html index.htm index.nginx-debian.html;

    charset utf-8;

	location / {
            try_files $uri $uri/ /index.php?$query_string;
            gzip_static on;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
        include snippets/fastcgi-php.conf;
    }

	# pass PHP scripts to FastCGI server
	#
	#location ~ \.php$ {
	#	include snippets/fastcgi-php.conf;
	#
	#	# With php-fpm (or other unix sockets):
	#	fastcgi_pass unix:/run/php/php7.4-fpm.sock;
	#	# With php-cgi (or other tcp sockets):
	#	fastcgi_pass 127.0.0.1:9000;
	#}

	# deny access to .htaccess files, if Apache's document root
	# concurs with nginx's one
	#
	#location ~ /\.ht {
	#	deny all;
	#}
}

Save the file, then create a symlink:

ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled/api

Restart Nginx:

systenctl restart nginx

Secure the API domain

sudo certbot --nginx -d api.brezel.example.io

Add the database

NameValue
Database namebrezel
Database user namebrezel
Password(Click Generate)

4. Create a new user and environment for Brezel

  1. Create the new user.
adduser brezel
  1. Add your new user to the www-data group to ensure the correct permissions for the Nginx web server.
usermod -aG www-data brezel

Set up a basic environment for the new user by copying the /etc/skel directory.

cp -r /etc/skel /home/brezel/
  1. Change the ownership of the copied /etc/skel directory to the new user.
chown -R brezel:www-data /home/brezel/

5. Connect the server to GitLab

The Brezel instance will be deployed to the API subdomain. The SPA domain will receive the contents of the minified frontend found in the dist/ folder.

Create SSH keys for GitLab

  1. Switch to the new user.
su - brezel
  1. Generate an RSA key pair:
ssh-keygen -b 4096

This will output:

Generating public/private rsa key pair.
Enter file in which to save the key (/var/www/vhosts/brezel.example.io/.ssh/id_rsa):

The path is fine. Hit enter.

Created directory '/var/www/vhosts/brezel.example.io/.ssh'.
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 /var/www/vhosts/brezel.example.io/.ssh/id_rsa.
Your public key has been saved in /var/www/vhosts/brezel.example.io/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:hcsvjIXxM8ZS16X3IHIoGFwPSHr5Cjw35HOIZMEIW1c brezel@lvps5-35-243-342.dedicated.hosteurope.de
The key's randomart image is:
+---[RSA 4096]----+
|...oo+Eoo     .  |
| o...oo+ + o o   |
|.   + * + * = o  |
|   + = X = o o o |
|    = O S       .|
|     + @ +       |
|      o o .      |
|         .       |
|                 |
+----[SHA256]-----+

Now, go to GitLab, to the repository of your Brezel instance and go to Settings > Repository > Deploy Keys. We want our server to be able to read from the GitLab repository. Paste the contents of ~/.ssh/id_rsa.pub to the Key field. Give it a meaningful title like Production [brezel.example.io].

Clone the repository

  1. Move to your new user’s web root directory where we will clone the Laravel repository.
cd /var/www/vhosts
  1. Install Git if it’s not already installed.
sudo apt-get install git

Clone the instance repository:

git clone git@gitlab.kiwis-and-brownies.de:kibro/basedonbrezel/example.git api.example.brezel.io

Go to the cloned directory:

cd api.example.brezel.io

6. Set up Brezel

Install composer and do

mv composer.phar ~/bin/composer

Enter your private package credentials:

Only needed if you don’t deploy via a pipeline Change $PACKAGE_TOKEN and $PACKAGE_TOKEN_USER to a GitLab token and user that can read brezel/api

php ~/bin/composer config --auth gitlab-token.gitlab.kiwis-and-brownies.de $PACKAGE_TOKEN_USER "$PACKAGE_TOKEN"

Then, install dependencies:

Only needed if you don’t deploy via a pipeline

php ~/bin/composer install

If you want to merge pdf files or use file thumbnails, you need to install ghostscript and the php imagick extension respectively.

Update folder permissions for the storage directory:

chmod -R 775 storage

Next, configure your environment:

Database

For the database credentials:

Variant 1: Use root credentials

TENANCY_DATABASE="brezel"
TENANCY_USERNAME="root"
TENANCY_PASSWORD="<password>"

Variant 2: Use a privileged database user

Or, if you have root privileges, you can give the brezel MySQL/MariaDB user SUPER privileges:

GRANT SUPER ON *.* TO 'brezel'@'localhost';
FLUSH PRIVILEGES;

And set the following credentials:

TENANCY_DATABASE="brezel"
TENANCY_USERNAME="brezel"
TENANCY_PASSWORD="<password>"

Initialization

If the database credentials were set up, you can initialize the instance with

php bakery init

Now, you can add your system

php bakery system create example

And fill it with your config:

php bakery apply
php bakery load

7. Set up Brezel SPA

Follow the SPA instructions in the Pipeline guide .

8. Set up the pipeline

Follow the Pipeline guide .

9. Install and configure supervisor

For async workflows and other background jobs to work, we need to install supervisor.

apt-get update
apt-get install supervisor

Reinitialize Brezel:

php bakery init

Now copy supervisor.conf.example to supervisor.conf and adjust the socket names if desired.

Then start supervisor in your instance directory with:

supervisorctl start all

Check that all jobs are up and running:

supervisorctl status