Getting Started

Bakery is a CLI tool that binds together various tools to manage a matrixed build of container images.

Prerequisites

uv (includes Python)
just

3rd Party Tools

Tool	Used By	Purpose
docker buildx bake	`bakery build --strategy bake`	Build containers in parallel
docker, podman, or nerdctl	`bakery build --strategy build`	Build containers in series
dgoss	`bakery run dgoss`	Test container images for expected content & behavior

Note

Additional tool integrations (hadolint, trivy, wizcli, openscap) are planned. See the architecture diagrams for the full roadmap.

Installation

Install bakery using uv tool:

uv tool install 'git+https://github.com/posit-dev/images-shared.git@main#subdirectory=posit-bakery&egg=posit-bakery'

Examples

See the Bakery Examples repository for step-by-step tutorials on creating and managing container image projects with Bakery.

Usage

Tip

See the architecture diagrams for detailed tool behavior.

Show the commands available in bakery.

bakery --help

# or

bakery help

Step 1. Create a project

Create a new project
```
bakery create project
```
This command will create a new project configuration file in the bakery context.
Make changes to the bakery.yaml file

Update the contents of the project configuration file. A new project configuration file includes a default set of values.
- Document the source code Repository
- Configure image Registry entries to tag and push images to specific registries

Step 2. Create an image

Create a new image
```
bakery create image fancy-image
```
This command:
- Creates a directory for the image (fancy-image in this example)
- Creates a template/ subdirectory
- Writes a default set of template files
- Adds the image to the images section of the bakery.yaml file
Make changes to the bakery.yaml file

Update the Image definition.
- Define Image Variants
- Set Dependency Constraints
Make changes to the default Jinja2 templates

The default set of templates provide only a basic skeleton of what is required to define and build an image; you will need to modify these generic templates.

See the available Jinja variables in the templating documentation.
Add additional templates that will be rendered for each image version

You can add additional template files that will be created for each new image version.

Template files must end with the .jinja2 file extension.

Step 3. Create an image version

Create a new version of the image
```
bakery create version fancy-image 2025.01.0
```
This command
- Creates a subdirectory for the image version (fancy-image/2025.01.0 in this example)
  
  The --subpath flag can be used to create the version directory in a different location
- Updates the bakery.yaml file with the new image version
- Sets the new image to latest
  
  The --no-mark-latest flag skips marking the image as the latest
- Renders the templates created in Step 2, replacing the values
Make changes to the bakery.yaml file

Update the ImageVersion definition.
- Set Dependency Versions

Step 4. Build the image(s)

Preview the bake plan [OPTIONAL]
```
bakery build --plan
```
The build --strategy bake command creates a temporary JSON file that is passed to docker buildx bake.
Build the container images
```
bakery build
```

Step 5. Run the tests

Run the dgoss tests against all the images
```
bakery run dgoss
```
Additional run options can be specified using Goss options in bakery.yaml on a per image or per variant basis

Bakery Concepts

Project Structure

Bakery establishes a directory structure, referred to as a project. The project configuration is stored in the bakery.yaml.

By default, bakery uses the invocation directory as the project context. You can use the --context flag to override the default behavior.

bakery --context /path/to/directory

A bakery project can include one or more images. Each image can optionally have one or more variants. By default, there are two variants: Standard and Minimal. Each image should have one or more versions. Each version can have one or more OSes.

.
├── bakery.yaml
├── fancy-image/
│   ├── 2024.11.0/
│   ├── 2025.01.0/
│   └── template/
└── more-fancy-image/
    ├── 2024.12.0/
    ├── 2024.12.1/
    ├── 2025.02.0/
    └── template/

Image Tags

Bakery adds the following default tags for all versions of the image:

Standard Image	Minimal Image	Structure
`2025.01.0-ubuntu-22.04-std`	`2025.01.0-ubuntu-22.04-min`	`<version>-<os>-<type>`
`2025.01.0-ubuntu-22.04`	❌	`<version>-<os>`
Added if `os == primary_os`
`2025.01.0-std`	`2025.01.0-min`	`<version>-<type>`
`2025.01.0`	❌	`<version>`

Bakery also adds the following tags to the latest image version:

Standard Image	Minimal Image	Structure
`ubuntu-22.04-std`	`ubuntu-22.04-min`	`<os>-<type>`
`ubuntu-22.04`	❌	`<os>`
Added if `os == primary_os`
`std`	`min`	`<type>`
`latest`	❌	`latest`