asdfvm/asdf repository overview

⁠Current versions

⁠Docker Latest Builds

⁠asdf-vm base images

Works with asdf⁠ >=0.16.0

This repository contains base Docker images tailored for the versatile version manager tool, asdf-vm. These base images are designed with a flexible ONBUILD feature, enabling the creation of specialized images pre-equipped with predefined asdf⁠ plugins.

⁠Overview

⁠Base Image Structure

The base image Dockerfile provided here serves as a fundamental building block. It includes essential configurations to set up asdf-vm along with necessary tools like Git, curl, and bash within an Linux environment. An ONBUILD directive is employed to facilitate the automatic installation of specified asdf⁠ plugins and versions when building new images based on this template.

⁠Utilising ToolSet Images

Examples of other Dockerfiles demonstrate how these base images can be utilized to construct specialized images for different tools or software stacks. By leveraging the base image and utilizing a docker-compose file, users can easily set up and install asdf plugins as per their requirements.

To make this your own repository, you can fork⁠ this repo and update the following environment⁠ variables to your liking.

# labels
NAME="asdf-vm"
MAINTAINER="jrosco"
DESCRIPTION="asdf version manager toolset"
URL="https://github.com/jrosco/docker-container-asdf"
REPOSITORY=$URL

# docker registries
ASDF_REGISTRY_BASE="ghcr.io/jrosco/$NAME"
ASDF_REGISTRY_TOOLSET="$ASDF_REGISTRY_BASE-toolsets"

ASDF_IMAGE_TAG="alpine3-v0.19.0"
PACKAGE_NAME="helm helmfile helm-diff"

An example is showcased using Helm packages within an Alpine Linux environment and other examples found in the toolset-docker-images⁠ directory.

docker-compose.yml:

services:
  alpine:
    image: ${ASDF_REGISTRY_TOOLSET}/helm:build
    build:
      context: .
      dockerfile: Dockerfile
      args:
        asdf_image: "${ASDF_REGISTRY_BASE}:${ASDF_IMAGE_TAG}"
        packages: "${PACKAGE_NAME}"
      platforms:
        - "linux/amd64"

Example Dockerfile and build:

ARG asdf_image="ghcr.io/jrosco/asdf-vm:alpine"
FROM $asdf_image

⁠Build the image

docker build --platform linux/amd64 \
    --build-arg \
    packages="awscli:latest:set helmfile:latest:set helm:latest:set kustomize:latest:set" \
    --build-arg \
    asdf_image="ghcr.io/jrosco/asdf-vm:alpine3-v0.19.0" \
    -t helm-toolset:alpine .

⁠Get the installed package versions and details

docker run -it helm-toolset:alpine asdf info
docker run -it helm-toolset:alpine asdf current

⁠Docker Build Arguments --build-arg

Each Dockerfile utilizes the following build arguments:

• asdf_image: The base image to use for the build. This should be one of the base images provided in the base-images⁠ directory.
• packages: A list of asdf⁠ plugins to install. These should be space-separated and match the names of the plugins in the asdf-community GitHub repository⁠

packages support the following formats

The asdf_image and packages arguments are optional. If not provided, the build will default to installing the latest version of asdf and no plugins.

⁠Docker Image Tagging Strategy

When building toolset images, use a consistent tagging strategy for easy identification and version management. The docker-compose.yaml files in the toolset-docker-images⁠ directory demonstrate a multi-tag approach using variables from .env:

tags:
  - "${ASDF_REGISTRY_TOOLSET}/toolset:latest"                                      # Generic latest
  - "${ASDF_REGISTRY_TOOLSET}/toolset:alpine-${ALPINE_VERSION}-${ASDF_VERSION}"   # OS + ASDF version
  - "${ASDF_REGISTRY_TOOLSET}/toolset:alpine-${ALPINE_MAJOR_VERSION}.${ALPINE_MINOR_VERSION}" # OS major.minor
  - "${ASDF_REGISTRY_TOOLSET}/toolset:alpine-${ALPINE_VERSION}-${ASDF_VERSION}-build${BUILD_NUMBER}" # Full with build #

Tag components:

• alpine / debian — Base operating system
• ALPINE_VERSION / DEBIAN_VERSION — Full OS version (e.g., 3.20.0, 12.7)
• ASDF_VERSION — asdf version (e.g., v0.13.0)
• BUILD_NUMBER — Build iteration counter

Tagging recommendations:

• Use semantic versioning (v1.0.0) for toolset releases
• Include the base OS name and version for clarity
• Add asdf and build metadata for full traceability
• Set one tag as latest to point to the most recent stable release
• Use build numbers to distinguish rebuilds of the same version combination

⁠Adding Your Own .tool-versions File on Build

You can add your own .tool-versions file, for example:

package_name1 version_number
package_name2 version_number

Naming the file .tool-versions will automatically detect the file and COPY it to the image on build.

To add a custom file (e.g., using a different name), you need to use the Docker COPY command and set ASDF's environment variable correctly:

WORKDIR /tmp/  # Only required if you want to put the file in a different location from the default `/asdf/`
ENV ASDF_TOOL_VERSIONS_FILENAME=custom-tool-version
COPY custom-tool-version ./
RUN bash /init/install-asdf-package

See the asdf reference for more details⁠.

⁠Getting Started

To get started, follow these steps:

1. Clone the Repository: Clone this repository to your local environment.
2. Explore Base Images: Navigate to the base-images⁠ directory to explore the base images available.
3. Customize Dockerfiles: Review and customize the Dockerfiles provided in the base-images⁠ directory to suit your needs. Modify the ONBUILD directives, add or remove packages, and adjust versions as required.
4. Build Specialized Images: Utilize the base images as templates to construct specialized images for your toolsets or software stacks. Refer to the provided examples and adjust the docker-compose files and build configurations according to your preferences.
5. Run and Test: Once built, run the images in your environment and test to ensure proper functioning.

⁠Contributing

Contributions to enhance or expand the existing base images or examples are welcome. Feel free to submit pull requests, suggest improvements, or report issues in the repository.

⁠License

MIT License

See LICENSE⁠ to see the full text.