Run GLRD

This guide covers how to set up and run the glrd and glrd-manage tools. Choose the method that fits your environment.

Prerequisites

All methods require:

• A network connection to the Garden Linux GLRD Amazon S3 bucket for read queries (unless using local file input).
• Amazon Web Services (AWS) credentials with write access to the S3 bucket when using glrd-manage --s3-update.

For local Python installation, you also need:

• Python 3.10 or later
• A GITHUB_TOKEN environment variable — required only if you plan to generate release data from GitHub history (the --create-initial-releases flag). The token needs no special scopes for the public Garden Linux repository. You can obtain one from GitHub Settings → Developer settings → Personal access tokens or, if you have the GitHub CLI installed, by running export GITHUB_TOKEN=$(gh auth token).

Install locally with Poetry

1. Clone the repository:

   git clone https://github.com/gardenlinux/glrd.git
   cd glrd

2. Install dependencies:

   poetry install

3. Verify the installation:

   poetry run glrd --help
   poetry run glrd-manage --help

After installation the tools are available as glrd and glrd-manage within the Poetry virtual environment, or via .venv/bin/glrd and .venv/bin/glrd-manage if you activate the environment.

Run in a container

You can run both tools from the pre-built container image without installing Python or Poetry locally.

Use the pre-built image

# Query releases (read-only, no credentials needed)
podman run -it --rm ghcr.io/gardenlinux/glrd glrd

# Manage releases (requires AWS credentials)
podman run -it --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  ghcr.io/gardenlinux/glrd glrd-manage

Build and run locally

podman build -t glrd .

# Query releases
podman run -it --rm glrd glrd

# Manage releases
podman run -it --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  glrd glrd-manage

Run in a GitHub Actions workflow

The GLRD repository publishes a GitHub Action you can use directly in your workflows. The following example retrieves the latest minor and nightly versions:

steps:
  - name: Get latest Garden Linux minor version
    id: gl_version_latest
    uses: gardenlinux/glrd@main
    with:
      cmd: glrd --no-header --type minor --latest --fields Version

  - name: Use latest Garden Linux minor version
    run: echo "${{ steps.gl_version_latest.outputs.result }}"

  - name: Get latest Garden Linux nightly version
    id: gl_version_nightly
    uses: gardenlinux/glrd@main
    with:
      cmd: glrd --no-header --type nightly --latest --fields Version

  - name: Use latest Garden Linux nightly version
    run: echo "${{ steps.gl_version_nightly.outputs.result }}"

The result output contains the raw text output of the cmd command.

Query JSON data manually

You can fetch raw JSON release data directly from the S3 bucket without using the glrd CLI. The available files are:

• releases-major.json
• releases-minor.json
• releases-nightly.json
• releases-dev.json

Example — fetch all major releases:

curl -s https://gardenlinux-glrd.s3.eu-central-1.amazonaws.com/releases-major.json

AWS authentication for glrd-manage

glrd-manage requires write access to the S3 bucket when --s3-update is passed. Configure credentials using any method supported by the AWS Boto3 credentials chain.

When running in a container, pass credentials via environment variables:

podman run -it --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_SESSION_TOKEN \
  ghcr.io/gardenlinux/glrd glrd-manage --create minor --version 1592.7

The environment variables are forwarded from the host shell into the container without exposing their values in the command line.

Related topics

• Garden Linux Release Database (GLRD)How-to guides for running, querying, and managing Garden Linux Release Database (GLRD) entries.
• Query Garden Linux ReleasesStep-by-step examples for querying the Garden Linux Release Database (GLRD) with the glrd CLI tool.
• Manage GLRD entriesStep-by-step examples for creating, updating, and deleting Garden Linux releases database entries using the glrd-manage CLI tool.
• Garden Linux Release Database (GLRD)Overview of the Garden Linux Release Database (GLRD): a system for managing and querying Garden Linux release information.
• GLRD CLI ReferenceComplete flag and option reference for the glrd and glrd-manage command-line tools.
• GLRD Release SchemaJSON schema reference for Garden Linux Release Database (GLRD) release types: major, minor, nightly, dev, and next.
• GLRD Release LifecycleExplains lifecycle dependencies between major and minor releases, default date calculations, nightly and dev date rules, and the GLRD versioning scheme.