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

Get a Brezel repo ready. Either Fork Brezel/Brezel, or, 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:

This is easiest with mise!

On Linux and MacOS (any Unix-like system really), we highly recommend setting it up for an easier time!

Steps with mise:
Terminal window
```
mise run install
```
Manual steps without mise:
Terminal window
```
composer install
npm install
```

Setup your Brezel

This is again easiest with mise!

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
```
mise run init
```
Or manually:
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:

With mise installed and a shell that supports mise shell alias (see mise docs):
Terminal window
```
u
```
Or manually:
Terminal window
```
mise run update
```
or without mise:
Terminal window
```
./bin/u
```
Or completely manually:
Terminal window
```
php bakery apply
php bakery load
```
Hint: for the first seed after system creation you might need to run those multiple times until it settles down!

Start the servers

Using the helper script (recommended)

Install ZelliJ and ensure mise is also available.
Run
Terminal window
```
mise run serve
```
(Or ./bin/serve if you don’t have mise installed)
A new terminal window will open with all necessary servers running, including an interactive session in the directory to run things like php bakery apply, bin/u or any mise commands.

Platform specific instructions

macOS, Linux

API

Laravel Valet based

This section is untested on linux but should work

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.

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.