Getting started

Before you begin

Make sure you have access rights to the Kibro package registries (currently, that is by being invited to the Brezel GitLab namespace) and that you fulfill the system requirements.

Then, complete the following steps to set up your Brezel instance:

API Composer registry configuration

This section ensures that you are able to retrieve the brezel/api composer package.

First, generate a GitLab personal access token with the scope set to, at minimum, api. Then, add your access token to your global composer config as follows:

composer config gitlab-token.gitlab.kiwis-and-brownies.de $GITLAB_TOKEN

Refer to the GitLab Guide for details.

SPA NPM registry configuration

This section ensures that you are able to retrieve the @kibro/brezel-spa, @kibro/brezel-recipes, @kibro/brezel-brotcast, and other @kibro npm packages.

First, make sure you are authenticated to the package registry. Try the instance-level endpoint, as described here.

Then, add the @kibro registry:

npm config set @kibro:registry https://gitlab.kiwis-and-brownies.de/api/v4/packages/npm/
echo "//gitlab.kiwis-and-brownies.de/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}" >> $HOME/.npmrc

The trailing slash is important, as package managers like pnpm choke on it otherwise.

Installation

Fork Brezel/Brezel. If you cloned an existing Brezel instance, you can skip this step. Fork and clone the repo, then replace all example content with your system name.
Go to the directory of your instance and install the necessary dependencies:
Terminal window
```
composer install
npm install
```
Create a new MySQL database called brezel_meta, or any other name you prefer. This will be the meta database for one or more Brezel systems in this instance. In MySQL, execute the following command:
```
CREATE DATABASE brezel_meta
```

Setup your Brezel

Copy the .env.example file to .env and edit the .env file. Make sure to set APP_ENV to the appropriate value (local, staging or production). This determines if passwords are seeded as secret or not, among other things. For a full list of settable environment variables, consult the environment variable reference. To get started, make sure to set the following variables:

APP_URL="http://mybrezel.test"

BREZEL_EXPORT_URL="https://export.staging.cluster-sw.brezel.io"

TENANCY_HOST=127.0.0.1
TENANCY_PORT=3306
TENANCY_DATABASE="brezel_meta"
TENANCY_USERNAME="root"
TENANCY_PASSWORD="password"

# Note: variables that are prefixed with `VITE_` are baked into client JS scripts.
# Do not put sensitive values here.
VITE_APP_API_URL="http://mybrezel.test"
VITE_APP_SYSTEM=example

Initialize the database:
Terminal window
```
php bakery init
```
Create one or more Brezel systems by using the following command. Replace example with the name of your system.
Terminal window
```
php bakery system create example
```
The corresponding directory systems/example can hold .bake-configuration files that can be synced to the example database. To do this, you can run the following command:
Terminal window
```
php bakery apply
```
When creating the system for the first time, it is possible that the apply command has to be run two times to create the default admin user:
Terminal window
```
php bakery apply
```

Start the servers

Windows

For Windows, we offer a simple script that starts a terminal window with all necessary servers running, including an interactive powershell session in the directory to run things like php bakery apply.

Look at the windows prerequisites for more details what you need to use this.

Now just go to the Brezel directory and run the following script in powershell:

bin\serve_on_windows.ps1

This gives you a basic, running Brezel instance. For websocket or cron support extra steps are needed.

For websockets clone brotcast into C:\Code\Brezel. This path might get configurable in the future, but for now, it’s not. Annoy Oli or implement it yourself as a param for the script.

macOS, Linux

API

If you used valet in the webserver setup:

valet link

Now valet created the symbolic link mybrezel.test to your Brezel instance. This is where the Brezel API is reachable from now on.

SPA

In the Brezel directory, start the SPA development server:

npm run serve

The service will listen on localhost:8080 or the nearest open port.