Skip to content

v3 Documentation

Jump to bottom
Fabian Holler edited this page Nov 18, 2022 · 2 revisions

Baur 3 Documentation

Table of Content

Definitions

  • baur Repository
    A baur repository is a directory hierarchy, containing one or more .app.toml configuration files.
    A baur repository is usually part of a git repository.
  • baur Application
    A baur application, defines one or more tasks in it's .app.toml file.
    The file is stored in the root of the application directory.
  • Task
    A task consists of a set of inputs, a command that is executed and
    optionally outputs that are produced by the command. Outputs can be files or docker images.
    The same output needs to be created when the inputs of a task are the same.

Environment Variables

Baur supports to overwrite settings via environment variables.
The following environment variables are supported:

  • BAUR_POSTGRESQL_URL sets the PostgreSQL URL for the baur database
  • DOCKER_HOST
  • DOCKER_API_VERSION
  • DOCKER_CERT_PATH
  • DOCKER_TLS_VERIFY
  • DOCKER_CONFIG
  • AWS_ACCESS_KEY_ID
  • AWS_DEFAULT_REGION
  • AWS_SECRET_ACCESS_KEY

Configuration File Reference

baur configuration files are in TOML format.
Information about the TOML syntax can be found at: https://toml.io.

.baur.toml - Repository Configuration File

When baur is run, it looks for a .baur.toml file in the current directory, if it does not exist, it checks recursively in the parent directories until either a .baur.toml file is found or the filesystem root is reached. The file containing the .baur.toml file identifies the repository root directory.

An initial .baur.toml file can be generated by running:

baur init repo

The file defines general option that are valid for the whole repository.

  • config_version
    REQUIRED
    is an internal value and should not be changed manually. It is used by baur to check if the configuration file format is compatible with the executed baur binary. \

[Database]

  • postgresql_url
    specifies the URL to a PostgreSQL database that is used to store information about past task runs.
    The URL can be a PostgreSQL Connection String or URI. It is overwritten by the environment variable BAUR_POSTGRESQL_URL.

[Discover]

  • application_dirs
    REQUIRED
    is a list of directory paths in which baur searches for .app.toml configuration files.
    The paths are relative to the directory containing the .baur.toml file.

  • search_depth
    REQUIRED
    specifies how many directories the search descends from each listed application_dirs directory.

.app.toml - Application Configuration File

The file specifies configuration options for a baur application.

An exemplary .app.toml file can be generated by running:

baur init app

  • name
    REQUIRED
    defines the name of the application.
    . and * characters are not allowed in the name.
    Application names must be unique per a baur repository.

  • includes
    is a list of include references which are imported and become a part of the application.
    The format is documented in the chapter includes Reference format.

[[Task]]

  • name
    REQUIRED
    defines the name of a task.
    . and * characters are not allowed in the name.
    Task names must be unique per application. Multiple applications can have tasks with the same name.

  • command
    REQUIRED
    specifies the command that the task executes when it is run.
    The first element in the list is the name of a file to be executed. If the name does not contain a path separator character, the location of the binary is looked up via the PATH environment variable.
    The following elements are arguments for the binary.
    The command is run in the application directory.

  • includes
    lists Input or Output sections defined in include files that the task imports .
    The format is documented in the chapter includes Reference format.

includes Reference format

The references are specified in the format:

FILEPATH#INCLUDE_ID

FILEPATH is relative to the application directory.
INCLUDE_ID is an identifier that is specified in the include section.

[[Task.Input]]

Defines the Inputs, that when changed can influence the created output or if the task executes successfully.
baur run runs tasks for which no database record with the current inputs exist.
Same inputs means, that the content of the tracked files are and the values of tracked environment are the same.

A task must define at least 1 Input.

[[Task.Input.EnvironmentVariables]]

The sections defines names of environment variables that are tracked as inputs.

  • names
    REQUIRED
    is a list of environment variable names.
    Glob patterns can be specified to match multiple variables.
    Environment variable names are case-sensitive.
    Variables that are declared but not assigned are treated the same then non-existing variables.
    Variables that are defined but have an empty string assigned, are tracked.
    As glob patterns the syntax from Golang's filepath.Match() function.

  • optional
    If disabled, baur commands that evaluate the inputs of the task fail if one of the names elements do not match an existing environment variables.
    If the name is a glob pattern, it must match at least one environment variable.
    Default: false

[[Task.Input.File]]

The section defines files that are tracked as inputs.

  • paths
    REQUIRED
    Is a list of glob patterns that match files.
    All paths are relative to the repository root.
    As glob patterns the syntax from Golang's filepath.Match() function is supported.
    Additionally the ** pattern is supported, to match files recursively.

  • optional
    If false, all patterns in paths must match at least one file,
    all parts in a pattern that are paths must exist.
    If this is not the case, baur commands that evaluate the inputs of the task will fail.
    Default: false

  • git_tracked_only
    If enabled, file patterns only match files that are tracked in the git repository, untracked files are ignored.
    Default: false

[[Task.Input.GolangSources]]

Resolves Golang packages to source files. All imported packages are resolved recursively too.
Source files that belong the standard library are ignored.

  • queries
    REQUIRED
    Is a list of package queries. The pattern can be either repository relative file paths or query patterns that are forwarded to the go packages driver tool (usually go list).
    The query syntax described at https://github.com/golang/tools/blob/bc8aaaa29e0665201b38fa5cb5d47826788fa249/go/packages/doc.go#L17 is supported.
    Example: queries = ["./..."] resolves to all go source files in the application directory and the source files that are recursively imported.

  • environment
    Specifies environment variables that are defined when the go package driver tool (go list) is run.
    The format of each element is <VARIABLE-NAME>=<VALUE>.
    The tool runs in a clean environment, only the following variables from the current environment are inherited:

    • PATH
    • GOCACHE
    • XDG_CACHE_HOME
    • HOME
    • home
    • LocalAppData
    • USERPROFILE

  • build_flags
    Is a list of command-line flags that are passed through to the go package driver tool.

  • tests
    If enabled test files (*_test.go) are included.
    Default: false

[Task.Input.ExcludedFiles]

Specifies files that are excluded from the inputs.
Excluded files are evaluated after all other Input sections.

  • paths
    REQUIRED
    Is a list of glob patterns that match files to be excluded.
    All paths are relative to the application directory.
    As glob patterns the syntax from Golang's filepath.Match() function is supported.
    Additionally the ** pattern is supported, to match files recursively.
    If a part of pattern is a path and does not exist, it does not result in error.
[[Task.Output]]

Defines artifacts that are produced by running the command of the task and where they are uploaded to.
The section is optional.
If no outputs are specified, baur records in the database if the task execution was successful.
It is successful, if the command exits with code 0.

[[Task.Output.DockerImage]]
  • idfile
    REQUIRED
    Specifies the path of a file containing the docker image ID of the created image.
    The path is relative to the application directory.
    The file can be created by running docker build by specifying the --idfile parameter.
[[Task.Output.DockerImage.RegistryUpload]]

Defines where the image is uploaded to.
The standard docker mechanism to read authentication information is used, it is read from the user's config.json file or the file

  • registry
    The address of the docker registry.
    If it's empty the default of the docker daemon is used.

  • repository
    REQUIRED
    The repository.

  • tag
    REQUIRED
    The tag is applied to the image.

[[Task.Output.File]]
  • path
    REQUIRED
    Is an application directory relative path to a file. \
[[Task.Output.File.S3Upload]]

Specifies that the file is uploaded to an S3 bucket.
Authentication information can be supplied via environment variables and the configuration files supported by the AWS SDK.
See https://web.archive.org/web/20221118163559/https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html for more information.

  • bucket
    REQUIRED
    Is the name of the S3 bucket. \

  • key
    REQUIRED
    Is the S3 object key. \

[[Task.Output.File.FileCopy]]

Specifies a location to which the output file is copied.

  • path
    REQUIRED
    The destination path to which the file is copied.

Include Configuration Files

Include configuration files specify shareable section that can be imported in .app.toml files.

An initial include configuration file can be generated by running:

baur init include

The fields in the include files have the same meaning then their equivalent in the application config file. The format is very similar.

An include configuration file can have one or more [[Input]], [[Task]] or [[Output]] section.
Each section has on the top-level an include_id field. The field specifies the ID to be used when referencing it in includes fields.

Templating

baur configuration files have limited support for templating.
Templating syntax can only be used in values of configuration fields.
The Templating engine is based on Go Templates, everything that is supported by it can be used.

Additionally the following is supported:

Parameters

  • {{ .Root }}
    Is replaced with path to the repository root directory.

  • {{ .AppName }}
    Is replaced with the name of the application.

Functions

  • {{ gitCommit }}
    Arguments: none
    Returns the Git commit ID of the HEAD reference in the bau repository.

  • {{ env }}
    Arguments: string, environment variable name
    Returns the value of an environment variable. If the variable is not defined baur will fail.
    Example: Get the value of the environment variable $TERM: {{ env "TERM" }}

  • {{ uuid }}
    Arguments: none
    Generates and returns a UUID.

Clone this wiki locally