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
A Brezel based on a recent version of brezel/api. i.e. brezel/api@1.0.0 or higher.
GitLab repository for that Brezel instance
An Ubuntu or Debian based server satisfying the requirements
sudo access on that machine
Basic server setup
On a brand new, empty server
If this is a new server with nothing else on it, you should create a new system user with sudo privileges.
This user will not run Brezel, but will be used to set up the server and any administrative tasks.
(Using root for this is not recommended.)
Change the name of that user to your liking, we will use “kibro” here.
Terminal window
sudoadduserkibro
sudousermod-aGsudokibro
Harden the server
Add a public key for SSH access to the new user.
First, create a new key pair on your local machine:
Terminal window
ssh-keygen-t-C"kibro"
Make sure to put those keys (public and private) in a safe and secure place.
Possibly share them with the team using a password manager (e.g. Passbolt).
Now, still on your local machine run this with the correct values to copy the public key to the server so you can log in with the private key:
Now you can validate that the bouncer and the engine are running:
Terminal window
sudocsclibouncerslist
To see more detailed infos about what CroudSec is doing, you can check the metrics:
Terminal window
sudocsclimetrics
On an already setup server
You fall into this category if you already have a user with sudo access on the server.
Now create a new user for your brezel instance:
Terminal window
sudoadduserbrezel
This will be the user that runs and operates the Brezel instance.
Most of the actually Brezel related setup in this guide will use this user, only some commands will require sudo and thus the other user.
Rule of thumb: If sudo is NOT used in a command, try it first with brezel, especially for any php commands.
(If additional instructions don’t say otherwise.)
Install needed dependencies
Use our sudo user for this (in our case kibro).
Nginx, PHP, PHP extensions, and other necessary dependencies:
If sudo snap install --classic certbot does not work because you are behind some kind of firewall or don’t have access to snap, you can also install certbot via sudo apt install certbot python3-certbot-nginx
In the installation process, read closely what it asks you and answer accordingly.
You want to remove the test database and disallow remote root login.
And you should set a secure password for the root user.
At this point you can already create a “brezel” database user with the necessary permissions while you are at it.
CREATE USER 'brezel'@'localhost' IDENTIFIED BY '<your secure password>';
GRANT ALL ON *.* TO 'brezel'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;
Server Performance Tweaks
These are recommended performance tweaks for your server.
You can skip them, but your Brezel might not perform as well as it could.
Nginx configuration
Ensure these values in your top level/etc/nginx/nginx.conf file:
worker_processes auto;
events {
worker_connections 2048;
}
If they have already been set, be sure to change the values and not just add a new line with the same directive.
Restart Nginx:
Terminal window
sudosystemctlrestartnginx
Configure the Database
Adjust your database configuration in /etc/mysql/my.cnf by adding this block to the very bottom:
[mysqld]
max_connections = 500
innodb_buffer_pool_size = 4G
innodb_log_file_size = 512M
innodb_log_buffer_size = 16M
max_allowed_packet = 64M
If you are running MariaDB add the following options too:
thread_pool_size = 100
query_cache_size = 64M
Now restart the database (Use mysql if you are running MySQL):
Terminal window
sudosystemctlrestartmariadb
PHP-FPM configuration
Configure your php-fpm settings in /etc/php/8.4/fpm/pool.d/www.conf:
pm = dynamic
pm.max_children = 300
pm.start_servers = 20
pm.min_spare_servers = 20
pm.max_spare_servers = 50
pm.process_idle_timeout = 15s
You can either just paste these values at the end of the file or search for the values and change them.
PHP configuration
Finally, add the following values to your /etc/php/8.4/fpm/php.ini file:
This will create SSH keys for the brezel user and add them to GitLab as “deploy keys”.
That way, the server can pull your Brezel from the remote repository.
Switch to the brezel user.
Terminal window
su-brezel
Generate a new key pair:
Terminal window
ssh-keygen-b4096
You will be asked for a path. The default is probably fine.
Just ensure it is in the home directory of the brezel user (~/.ssh/id_<something>).
Hit enter.
You will then be asked for a passphrase.
We want no passphrase.
Leave the field empty and hit enter.
Hit enter again to confirm the empty password.
It will then output something like this:
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_<something>.pub to the Key field. Give it a meaningful title like Production [brezel.example.io].
Clone the repository
Move to your new user’s web root directory where we will clone the application repository to.
Terminal window
cd/var/www/vhosts/api.brezel.example.io
Install Git if it’s not already installed.
Terminal window
sudoapt-getinstallgit
Clone the instance repository (Get the SSH URL from the GitLab repository):
Make sure that the instance folder is owned by brezel and www-data with both having permissions to read, write and create files.
We also need to make sure that this ownership is propagated to all subdirectories and files, including newly created files.
That’s what the setfacl stuff is for.
In general 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.
Configure the environment
Ensure you are the brezel user and in the correct directory.
Terminal window
su-brezel
cd/var/www/vhosts/api.brezel.example.io
Copy the .env.example file to .env and adjust the values to your needs.
Terminal window
cp.env.example.env
Follow the comments and instructions in the .env file to set up the environment.
Here are some key tips:
APP_URL should be set to your API URL, e.g. https://api.brezel.example.io
Make sure to set APP_ENV to production and APP_DEBUG to false
Configure Brezel to use the database
Variant 1: Use root credentials
TENANCY_DATABASE="brezel_meta"
TENANCY_USERNAME="root"
TENANCY_PASSWORD="<password>"
Variant 2: Use a privileged database user
Or, if you have root privileges, you can create a brezel MySQL/MariaDB user with ALL privileges:
GRANT ALL ON *.* TO 'brezel'@'localhost' identified by '<password>' WITH GRANT OPTION;
FLUSH PRIVILEGES;
And set the following credentials:
TENANCY_DATABASE="brezel_meta"
TENANCY_USERNAME="brezel"
TENANCY_PASSWORD="<password>"
Install Brezel
Automatically via a Pipeline (recommended)
Follow the Pipeline guide guide.
You can skip step 1 in there as you already generated the keys.
Manually (not recommended)
Manual setup, proceed at your own risk
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
If you want to merge pdf files or use file thumbnails, you need to install ghostscript and the php imagick extension respectively.
Create your system
Now all dependencies should be installed, the needed files for SPA and API should be in place and the environment should be set up.
You can now create your system by its name by running the following command:
Terminal window
phpbakerysystem:createkab
Finally, run the setup commands:
Terminal window
phpbakeryinit--force
phpbakerymigrate--force
phpbakeryapply
phpbakeryload--force
phpbakerymake:supervisor
After this, a basic Brezel should be up and running. For the full functionality, you need to set up additional services.
Set up additional services
Setting up the brotcast environment
Installation
Available since:brezel/api@1.0.0
Since 1.0.0, Brezel ships with a Laravel Reverb based Brotcast server integrated!
Once you setup Supervisor, the server will be started automatically.
If you are not using the Laravel Reverb based Brotcast server, setup brotcast via Docker
Then create a docker-compose.yml file with the following content:
Especially increasing the available ports / file descriptors as well as switching to a different runtime might be beneficial.
Configuration
Configure the brotcast environment in the .env file:
# Broadcasting settings
BROADCAST_DRIVER=reverb# either `pusher` or `reverb` Use `reverb` if you are using the Laravel Reverb based Brotcast server (Recommended)
# Where to run the Brotcast server itself if using reverb
BREZEL_BROTCAST_SERVER_HOST=127.0.0.1
BREZEL_BROTCAST_SERVER_PORT=8086
# How to connect to the Brotcast server. This url should point to a pusher-compatible websocket server.
# If you are using the `pusher` driver, this should point to a brezel/brotcast-server instance
# If using the `reverb` driver, this should point to the Brotcast server endpoint defined above
BREZEL_BROTCAST_HOST=ws.brezel.example.io
BREZEL_BROTCAST_PORT=443
# Common Brotcast settings
# When using the `pusher` driver, these should be your pusher credentials and match what is configured in the Brotcast server
BREZEL_BROTCAST_APP_ID=brezel
BREZEL_BROTCAST_KEY=brotcast-pusher
BREZEL_BROTCAST_SECRET=an-alphanumerical-secret
BREZEL_BROTCAST_SCHEME=https
# Only relevant when using the `pusher` driver
BREZEL_BROTCAST_APP_CLUSTER=mt1
Set up crons
If you want to use event/cron, you need to set up a cronjob.
Very basically: this should trigger php bakery schedule in the directory of your instance every minute as the user that normally runs your brezel (when using nginx and following this setup it will be www-data).
How you achieve this depends on you, especially on your local setup, but on a server it makes sense to use cron.
Now you need to configure the export service in your .env file:
BREZEL_EXPORT_URL=http://127.0.0.1:5580
Install and configure supervisor
Supervisor handles the starting and stopping all the php-based services Brezel needs and ships with brezel/api.
That includes brotcast (if you use Reverb), the queues and so on.
Installing supervisor
Switch to a user with sudo privileges and install supervisor:
Terminal window
sudoapt-getupdate
sudoapt-getinstallsupervisor
Generate the supervisor configuration
Switch back to the brezel user and go into the instance directory.
Now copy supervisord.conf.example to supervisord.conf and adjust the socket names if desired.
Now run the following command to create the supervisor configuration:
Terminal window
phpbakerymake:supervisor
Now we register our supervisor programms with the supervisor daemon.
We want our supervisor programs to start on system boot.
For that, create the following systemd service file (/etc/systemd/system/supervisord-brezel.service) to start and manage our supervisor programms:
/etc/systemd/system/supervisord-brezel.service
[Unit]
Description=Run supervisord with the programs needed for the brezel instance on this server