Repository Structure

A catalog repository is a Git repository with a specific directory structure. The repository must contain an applications/ directory at its root, with each application in its own subdirectory:


your-catalog-repository/
└── applications/
    ├── hello-world/
    │   ├── metadata.md
    │   ├── template.yaml
    │   ├── values.yaml
    │   └── icon.png (optional)
    ├── data-processing/
    │   ├── metadata.md
    │   ├── template.yaml
    │   ├── values.yaml
    │   └── banner.jpg (optional)
    ├── hello-world-spanish/
    │   ├── metadata.md          (reuses hello-world's template)
    │   └── values.yaml
    └── ...

See the CIQ workflow template repository for an example of repository structure.

Required Files

Each application directory must contain metadata.md and a template. The template is normally the directory's own template.yaml, but an entry can instead reuse a template from another entry. Most directories also contain values.yaml, which declares the variables the template accepts; without it the template is offered with no configurable values.

metadata.md

A Markdown file with YAML frontmatter containing application metadata. The frontmatter must include:

id: An identifier for the application, unique within this repository. Any valid string is allowed -- see Application IDs. Two entries in the same repository that share an id are a conflict: Fuzzball keeps the first by directory name and skips the rest with a warning in the orchestrate log.
name: The display name for the application
category: The category to organize the application under. A list of available categories can be obtained with fuzzball workflow catalog list-categories.
description: A description of the application (in the Markdown body, not the frontmatter)

Optional frontmatter fields:

featured: Set to true to mark this application as featured (default: false)
key_art: Filename of an image file in the same directory to use as key art. The older spelling keyart is also accepted; if both are set, key_art is used unless the file it names is missing.
tags: List of tags for categorizing and searching
template: Directory name (not id or name) of another application in the same repository whose template this application uses. Only valid when the application has no template.yaml of its own -- see Reusing a template from another entry.

Example metadata.md:


---
id: https://example.com/apps/hello-world
name: Hello World
category: EXAMPLES
featured: false
key_art: icon.png
tags:
  - tutorial
  - beginner
---
This is a simple Hello World workflow that demonstrates basic Fuzzball functionality.

It prints a greeting message and can be customized with different container images.

Tip

When writing the description, put the most important information at the beginning. The workflow catalog displays only the first 2-4 lines in card view, though the full description is visible on the detail page.

template.yaml

A Fuzzfile template with placeholders for user-customizable values.

Example template.yaml:


{{- $shout := (default "Hello, world!" .Message | trim | upper) }}
version: v4
jobs:
  hello:
    image:
      uri: {{ .ContainerUri }}
    script: |
      #!/bin/sh
      echo "SHOUT: {{ $shout }}"
    resource:
      cpu:
        cores: {{ .Cores }}
      memory:
        size: {{ .Memory }}

Tip

The templating feature uses Go text/template and slim-sprig, allowing complex operations like conditional logic.

values.yaml

Defines all variables used in the template with their default values and descriptions.

Example values.yaml:


values:
  - name: ContainerUri
    display_name: Container image URI
    string_value: docker://alpine:latest
  - name: Message
    display_name: Message to display
    string_value: "Hello, world!"
  - name: Cores
    display_name: Number of CPU cores
    uint_value: 1
  - name: Memory
    display_name: Memory allocation
    string_value: 1GiB

Each value entry requires:

name: Variable name (matching the template placeholder without the dot)
display_name: User-friendly description
Value type: One of string_value, uint_value, bool_value, secret_value, or volume_value

Reusing a Template From Another Entry

An application that differs from an existing one only in its default values can point at that application's template instead of copying it. Add a template field to the frontmatter and leave out template.yaml:


---
id: https://example.com/apps/hello-world-spanish
name: Hello World (Spanish)
category: EXAMPLES
template: hello-world
---
The Hello World workflow, preconfigured with Spanish defaults.

The value of template is the other application's directory name under applications/ -- hello-world above. It is not that application's id and not its name, both of which are usually different from its directory name.

The application still needs its own metadata.md, and normally its own values.yaml; only the template is shared. When the referenced template changes, every application referencing it picks up the change on the next sync.

References resolve within a single repository and one level deep, so the referenced application must have a template.yaml of its own. Fuzzball skips an application, logging a warning in the orchestrate logs and leaving it out of the catalog, in any of these cases:

it references an application that does not exist, or one that has no template.yaml of its own
it has both a template.yaml and a template reference
it has neither

Warning

Template references require a Fuzzball release that supports them. An older deployment fails the repository sync altogether rather than skipping the referencing application, so no application in that repository is updated. Do not add referencing applications to a repository until every deployment reading it has been upgraded.

Optional Files

You can include image files (.png, .jpg, .jpeg, .webp, .svg) in each application directory for use as key art or icons. Reference these files using the key_art field in the metadata. You can also include subdirectories for scripts and other supplementary files that a workflow can pull in with data ingress.

Overview User Commands