Skip to content

Ensure docs use posit style. #339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
bschwedler wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Ensure docs use posit style. #339

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions posit-bakery/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

## Project Overview

Posit Bakery is a command-line tool for building, testing, and managing containerized images. It provides a structured approach to create, build, and test Docker images with variant support (e.g., Standard vs Minimal),
+ version management, OS variants, and dependency constraints.
Posit Bakery provides a command-line tool for building, testing, and managing containerized images. It offers a structured approach to create, build, and test Docker images with variant support (e.g., Standard vs Minimal), version management, OS variants, and dependency constraints.

The tool uses a YAML configuration file (`bakery.yaml`) and Jinja2 templates to define image builds, with support for parallel building via Docker Buildx Bake.

Expand Down
32 changes: 15 additions & 17 deletions posit-bakery/CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuration Overview

This document provides an overview of the configuration schema for Bakery, a tool for managing container images. The configuration is defined in a YAML file named `bakery.yaml`. A template for this file can be created using `bakery create project`.
This document provides an overview of the configuration schema for Bakery, a tool for managing container images. You define the configuration in a YAML file named `bakery.yaml`. Create a template for this file using `bakery create project`.

Fields marked as "*Required*" must be provided in the configuration file.

Expand Down Expand Up @@ -117,8 +117,7 @@ images:

### Repository

A Repository stores the metadata of the parent source code repository of the project. It is primarily used
for labeling images.
A Repository stores the metadata of the parent source code repository of the project. Bakery primarily uses it for labeling images.

| Field | Description | Default Value | Example |
|-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------|---------------------------------------------------------------------------------------------------|
Expand All @@ -138,9 +137,9 @@ A BaseRegistry represents a container image registry. It does not specify the re

### Registry

A Registry represents a container image registry and includes the name or repository of the image. It is a subclass of BaseRegistry.
A Registry represents a container image registry and includes the name or repository of the image. Registry extends BaseRegistry.

This type can be specified for an image or version, but cannot be specified at the top level of the bakery configuration.
You can specify this type for an image or version, but you cannot specify it at the top level of the bakery configuration.

A common use is pushing images to a repository name that is different from the name of the image.

Expand All @@ -154,7 +153,7 @@ A common use is pushing images to a repository name that is different from the n

### Image

An Image represents a container image managed by the project. Each image has one or more versions and optionally can have one or more variants and operating systems. New images can be created using the `bakery create image` command.
An Image represents a container image managed by the project. Each image has one or more versions and optionally can have one or more variants and operating systems. Create new images using the `bakery create image` command.

| Field | Description | Default Value | Example |
|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------|
Expand Down Expand Up @@ -231,8 +230,7 @@ images:

### ImageVariant

An ImageVariant represents a variant of an image, such as standard or minimal builds. Each variant is expected have its
own `Containerfile.<os>.<variant>`.
An ImageVariant represents a variant of an image, such as standard or minimal builds. Each variant should have its own `Containerfile.<os>.<variant>`.

| Field | Description | Default Value | Example |
|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
Expand All @@ -245,7 +243,7 @@ own `Containerfile.<os>.<variant>`.

#### Common Image Variants

By default, the image variants for an [Image](#image) will be set to an empty list `[]` f no `variants` are otherwise specified for the [Image](#image).
By default, Bakery sets the image variants for an [Image](#image) to an empty list `[]` if you do not specify `variants` for the [Image](#image).

A common pattern is to build a minimal image containing fewer dependencies, and a standard image that builds dependencies into the container.

Expand All @@ -262,9 +260,9 @@ variants:

### DependencyConstraint

Dependencies represents a list software dependencies that is installed in a specific image.
Dependencies represent software that Bakery installs in a specific image.

At the image level, these are specified through a VersionConstraint.
At the image level, you specify these through a VersionConstraint.

| Field | Description | Default Value | Example |
|-------|-------------|---------------|---------|
Expand All @@ -283,7 +281,7 @@ The versions can be defined explicitly as an array of strings, or in terms of a
| `max`<br/>*string* | Maximum version to include. | | `3.13.7`, `3.11`, `3` |
| `min`<br/>*string* | Minimum version to include. | | `4.2.1`, `4.3`, `4` |

At least one of `latest` or `max` must be specified.
You must specify at least one of `latest` or `max`.

If `latest` is `true` and no other fields are set, `count` defaults to `1`.

Expand Down Expand Up @@ -311,7 +309,7 @@ dependencyConstraints:

### ImageVersion

An ImageVersion represents a specific version of an image. Each version should be rendered from templates using the `bakery create version` command.
An ImageVersion represents a specific version of an image. Render each version from templates using the `bakery create version` command.

| Field | Description | Default Value | Example |
|-----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
Expand Down Expand Up @@ -365,9 +363,9 @@ os:

### DependencyVersions

Dependencies represents a list software dependencies that is installed in a specific image.
Dependencies represent software that Bakery installs in a specific image.

At the image level, these are specified by an array of strings.
At the image level, you specify these as an array of strings.

| Field | Description | Default Value | Example |
|-------|-------------|---------------|---------|
Expand Down Expand Up @@ -405,7 +403,7 @@ A NameEmail represents a name and email address pair.

### TagPattern

A TagPattern represents a pattern for tagging images. It can include placeholders that are replaced with actual values when generating tags.
A TagPattern represents a pattern for tagging images. It can include placeholders that Bakery replaces with actual values when generating tags.

| Field | Description |
|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
Expand All @@ -414,7 +412,7 @@ A TagPattern represents a pattern for tagging images. It can include placeholder

#### Pattern Templating

All [TagPattern](#tagpattern) `patterns` should be valid Jinja2 template strings.
All [TagPattern](#tagpattern) `patterns` must be valid Jinja2 template strings.

The following variables are available for use in `patterns`:
- `{{ Version }}`: The version of the image.
Expand Down
16 changes: 8 additions & 8 deletions posit-bakery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,15 +56,15 @@ bakery --help
bakery help
```

### Step 1. Create a project
### Step 1. Create a project {#create-project}

* Create a new project

```shell
bakery create project
```

This command will create a new project configuration file in the bakery context.
This command creates a new project configuration file in the bakery context.

* Make changes to the `bakery.yaml` file

Expand All @@ -74,7 +74,7 @@ bakery help
* Document the source code [Repository](./CONFIGURATION.md#repository)
* Configure image [Registry](./CONFIGURATION.md#registry) entries to tag and push images to specific registries

### Step 2. Create an image
### Step 2. Create an image {#create-image}

* Create a new image

Expand Down Expand Up @@ -108,7 +108,7 @@ bakery help

Template files must end with the `.jinja2` file extension.

### Step 3. Create an image version
### Step 3. Create an image version {#create-image-version}

* Create a new version of the image

Expand All @@ -135,7 +135,7 @@ bakery help

* Set [Dependency Versions](./CONFIGURATION.md#dependencyversions)

### Step 4. Build the image(s)
### Step 4. Build the image(s) {#build-images}

* Preview the [bake plan](https://docs.docker.com/build/bake/reference/) [OPTIONAL]

Expand All @@ -151,22 +151,22 @@ bakery help
bakery build
```

### Step 5. Run the tests
### Step 5. Run the tests {#run-tests}

* Run the `dgoss` tests against all the images

```shell
bakery run dgoss
```

Additional run options can be specified using Goss options in `bakery.yaml` on a per image or per variant basis
You can specify additional run options 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`.
The `bakery.yaml` file stores the **project** configuration.

By default, bakery uses the invocation directory as the project **context**.
You can use the `--context` flag to override the default behavior.
Expand Down
22 changes: 10 additions & 12 deletions posit-bakery/TEMPLATING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This document outlines the available Jinja2 macros in the Posit Bakery templating system for creating Docker images with
package installations.

Macros must be explicitly imported in every file in which they are used.
You must explicitly import macros in every file where you use them.

References:
- [Source Code](./posit_bakery/config/templating/macros)
Expand All @@ -20,10 +20,10 @@ References:
- [Quarto Installation and Management](#quarto-installation-and-management)

## Available Variables
The following variables are available by default for use in an image's Jinja2 templates. Additional values passed using
`--value` to `bakery create` or specified in the `values` field of an image version will also be available.
You can use the following variables by default in an image's Jinja2 templates. Additional values passed using
`--value` to `bakery create` or specified in the `values` field of an image version are also available.

Currently, `Containerfile` templates render as a unique file for each variant and OS. Using variant and OS based Jinja2 conditionals outside of `Containerfile` templates is not currently supported and will lead to unexpected results or errors.
Currently, `Containerfile` templates render as a unique file for each variant and OS. Bakery does not currently support using variant and OS based Jinja2 conditionals outside of `Containerfile` templates, and doing so leads to unexpected results or errors.

- `Image`: A dictionary containing information about the current image, version, variant, and OS.
- `Image.Name`: The name field of the image, e.g. `package-manager`, `workbench`, `connect`.
Expand Down Expand Up @@ -74,7 +74,7 @@ To wrap `setup()` in a Docker RUN statement, use:
#### Setup Posit Cloudsmith Apt Repositories
Renders commands to set up Posit Cloudsmith apt repositories. Requires `curl` to be installed prior to execution.

**NOTE:** This macro is included in `apt.setup()` or `apt.run_setup()`, so it does not need to be called separately unless `apt.setup()` is not used.
**NOTE:** `apt.setup()` and `apt.run_setup()` include this macro, so you do not need to call it separately unless you skip `apt.setup()`.

```jinja2
{{ apt.setup_posit_cloudsmith() }}
Expand All @@ -87,8 +87,7 @@ To wrap `setup_posit_cloudsmith()` in a Docker RUN statement, use:
```

#### Apt Clean Commands
Renders commands to clean and remove the apt cache to ensure minimal image layers. Clean commands should be run at the end of any RUN
statement that modifies packages, but it is implicitly included in most other macros that modify packages.
Renders commands to clean and remove the apt cache to ensure minimal image layers. Run clean commands at the end of any RUN statement that modifies packages. Most other macros that modify packages implicitly include clean commands.

```jinja2
{{ apt.clean_command() }}
Expand All @@ -97,7 +96,7 @@ statement that modifies packages, but it is implicitly included in most other ma
#### Apt Update and Upgrade
Renders commands to update the apt cache, upgrade packages, run dist-upgrade, and remove unneeded packages. Pass `False` to the `clean` argument to skip cleaning the cache if you want to append additional commands. Clean is `True` by default.

**NOTE:** This macro is called by `apt.setup()` and `apt.run_setup()`, so it does not need to be called separately unless `apt.setup()` is not used.
**NOTE:** `apt.setup()` and `apt.run_setup()` call this macro, so you do not need to call it separately unless you skip `apt.setup()`.

```jinja2
{{ apt.update_upgrade(clean = True) }}
Expand Down Expand Up @@ -154,7 +153,7 @@ To wrap `setup()` in a Docker RUN statement, use:
#### Setup Posit Cloudsmith DNF Repositories
Renders commands to set up Posit Cloudsmith DNF repositories. Requires `curl` to be installed prior to execution.

**NOTE:** This macro is included in `dnf.setup()` or `dnf.run_setup()`, so it does not need to be called separately unless `dnf.setup()` is not used.
**NOTE:** `dnf.setup()` and `dnf.run_setup()` include this macro, so you do not need to call it separately unless you skip `dnf.setup()`.

```jinja2
{{ dnf.setup_posit_cloudsmith() }}
Expand All @@ -167,8 +166,7 @@ To wrap `setup_posit_cloudsmith()` in a Docker RUN statement, use:
```

#### DNF Clean Command
Renders commands to clean the dnf package cache. Clean commands should be run at the end of any RUN
statement that modifies packages, but it is implicitly included in most other macros that modify packages.
Renders commands to clean the dnf package cache. Run clean commands at the end of any RUN statement that modifies packages. Most other macros that modify packages implicitly include clean commands.

```jinja2
{{ dnf.clean_command() }}
Expand All @@ -177,7 +175,7 @@ statement that modifies packages, but it is implicitly included in most other ma
#### DNF Update and Upgrade
Renders commands to upgrade packages, remove unneeded packages, and clean the cache. Pass `False` to the `clean` argument to skip cleaning the cache if you want to append additional commands. Clean is `True` by default.

**NOTE:** This macro is called by `dnf.setup()` and `dnf.run_setup()`, so it does not need to be called separately unless `dnf.setup()` is not used.
**NOTE:** `dnf.setup()` and `dnf.run_setup()` call this macro, so you do not need to call it separately unless you skip `dnf.setup()`.

```jinja2
{{ dnf.update_upgrade(clean = True) }}
Expand Down