b5 - a modular task runner

This is the second article of the series Local development with Docker, b5 and traefik. If you haven’t read the first part you can read about the intentions on why we developed b5.

Installation

I assume you are using macOS (I use 10.15.2) through the whole series. b5 is written in python and can be installed via homebrew.

1brew tap team23/b5 https://git.team23.de/build/homebrew-b5.git
2brew install b5

b5 itself has only python3 and a few libraries as dependencies which will be installed automatically if not present. But there are of course modules which need other dependencies like the Docker module which needs Docker and Docker Compose installed. In the Docker Desktop version they are bundled together.

1brew cask install docker

Conventions over configuration

We have a few conventions for software projects in our company. Our default project structure looks like this:

1- build
2    - config.yml
3    - Taskfile
4- web
5    - composer.json
6    - vendor

As you can see we place the actual application in a web folder. This is normally the folder which is deployed. Next to it is a build folder which is for infrastructure related things and the b5 configuration. The application itself does not know anything about b5 and never should. It is a tool only used during development. The last thing b5 needs is a local git repository. Later on you can use any b5 command from any folder inside your project. This works because b5 iterates up folder by folder searching for the .git directory. From there it goes to the configured run-path which is build by default but can be set via --run-path .

Taskfile

The Taskfile is in general a normal bash script which will be loaded by b5 using the bash source command . Because of this you may use anything you are already using when writing your bash scripts.

For defining tasks you will need to add functions following the task:name-schema. A simple Taskfile can look like this:

 1#!/usr/bin/env bash
 2# b5 Taskfile, see https://git.team23.de/build/b5 for details
 3 
 4task:css() {
 5    sassc input.scss output.css
 6}
 7 
 8task:composer() {
 9    (
10          # Use a sub shell to not remain in the web directory
11        cd ../web && \
12        composer "$@"
13    )
14}

Now you can call b5 composer {composer-cmd} from anywhere in your project.

More information about the Taskfile can be found in the documentation.

config.yml

The config.yml will be interpreted by b5 on execution and converted to bash variables. The following config file

1project:
2    name: Example Project
3  key: example
4paths:
5  web: ../web

is transformed into

1#!/usr/bin/env bash
2 
3CONFIG_project_name="Example Project"
4CONFIG_project_key="example"
5CONFIG_project_KEYS=("name", "key")
6CONFIG_paths_web="../web"
7CONFIG_paths_KEYS=("web")

More information about the config.yml can be found in the documentation.

The b5 docker module

The b5 docker module provides a convenient wrapper around Docker Compose. First of all we need to enable it inside the config.yml . This is as easy as adding a top level key named modules with a sub key named docker.

1project:
2  key: example
3modules:
4    docker:

It sets the COMPOSE_PROJECT_NAME for any commands called by it to the project key defined in the config.yml . This way we can ensure that different projects do not clash with each other because of equal named services in the docker-compose.yml.

By default b5 looks for a docker-compose.yml file inside of the build directory. To execute via the Taskfile you can define tasks like this:

 1#!/usr/bin/env bash
 2# b5 Taskfile, see https://git.team23.de/build/b5 for details
 3 
 4task:run() {
 5    docker:docker-compose up "$@"
 6}
 7 
 8task:halt() {
 9    docker:docker-compose down "$@"
10}
11 
12task:docker-compose() {
13    docker:docker-compose "$@"
14}

You can use any docker-compose command with task:docker-compose and you have two convenient tasks to start and stop the project.

Another feature is the option to define commands which can be used in the Taskfile . Here an example:

 1project:
 2  key: example
 3modules:
 4    docker:
 5        commands:
 6            composer:
 7                bin: composer
 8                service: php
 9                workdir: /app/web
10            phpunit:
11                bin: ["php", "./vendor/bin/phpunit"]
12                service: php
13                workdir: /app/web/
14            artisan:
15                  bin: ["php", "./artisan"]
16                  service: php
17                  workdir: /app/web/

These commands can be used inside the Taskfile like this:

 1#!/usr/bin/env bash
 2# b5 Taskfile, see https://git.team23.de/build/b5 for details
 3 
 4task:composer() {
 5    docker:command:composer "$@"
 6}
 7 
 8task:artisan() {
 9    docker:command:artisan "$@"
10}
11 
12task:phpunit() {
13    docker:command:phpunit "$@"
14}

In the next article of this series we will build an example project with b5, docker-compose and Laravel.

If you have any questions, do not hesitate to write me a mail.