amdresearch/ryzers/new-ryzer

Skill: new-ryzer

Scaffold a new Ryzer Docker package with all required files.

Usage

new-ryzer <category> <package_name>

• category — one of the existing directories under packages/ (e.g. llm, vlm, vla, robotics, vision, npu, ros, graphics, ide, adaptive-socs), or a new category name if none fits.
• package_name — lowercase, no spaces or hyphens (e.g. ollama, genesis, mobilesam).

What is a Ryzer?

A Ryzer is a self-contained, composable Docker package for running AI/ML/robotics workloads on AMD Ryzen AI hardware. Ryzers are layered — each one builds on top of a base image, and multiple ryzers can be chained together in a single build.

Users build and run ryzers with:

ryzers build <package_name>        # build a single package
ryzers build pkg1 pkg2 pkg3        # chain multiple packages (each layers on the previous)
ryzers run                         # run the most recently built image
ryzers run bash                    # override CMD to get a shell

Required Output

Every ryzer package lives at packages/<category>/<package_name>/ and must contain exactly these 4 files:

packages/<category>/<package_name>/
├── Dockerfile
├── config.yaml
├── test.sh (or test.py)
└── README.md

Optional extras: demo.sh, demo.py, LICENSE, additional test files.

File Specifications

1. Dockerfile

Rules:

• MUST start with ARG BASE_IMAGE and FROM ${BASE_IMAGE} — this enables layered composition.
• MUST include the copyright header.
• Set WORKDIR /ryzers before copying test/demo scripts.
• Copy test scripts into /ryzers/test_<package_name>.<ext> and chmod +x them.
• End with CMD /ryzers/test_<package_name>.<ext> so the default action validates the install.
• Use EXPOSE for any ports the package serves on.
• Keep installs minimal — only what this package needs.

Template:

# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT
 
ARG BASE_IMAGE
FROM ${BASE_IMAGE}
 
ENV DEBIAN_FRONTEND=noninteractive
 
# Install dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    <system-packages> \
 && rm -rf /var/lib/apt/lists/*
 
# Install Python packages
RUN pip3 install --no-cache-dir --break-system-packages \
    "<package1>==<version>" \
    "<package2>==<version>"
 
# Copy test script
WORKDIR /ryzers
COPY test.sh /ryzers/test_<package_name>.sh
RUN chmod +x /ryzers/test_<package_name>.sh
 
# EXPOSE <port>  # if applicable
 
CMD /ryzers/test_<package_name>.sh

Notes:

• Use --no-install-recommends and clean up apt lists to keep image size down.
• Use --no-cache-dir and --break-system-packages with pip3.
• Pin versions where possible for reproducibility.
• If the package needs build args, declare them with ARG and document in config.yaml.

2. config.yaml

This file configures Docker build and run flags. All fields are optional — include only what the package needs. An empty/commented config.yaml is valid.

Template:

# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT
 
### ryzers build options
 
# gpu_support: false          # add GPU support, default is true
# x11_display: false          # add X11 support, default is true
# init_image: "image_name"    # The first docker image to use as a base
                              # default is ryzers.RYZERS_DEFAULT_INIT_IMAGE
 
# build_arguments:            # List of ARGs to pass to the `docker build` call
# - "ARG=VALUE"               # E.g. - "PYTHON_VERSION=3.12"
 
 
### ryzers run options
 
# environment_variables:              # List of environment variables to set in the container
# - "ENV_VARIABLE=VALUE"              # E.g. "PYTHONPATH=/path/to/python"
 
# port_mappings:
# - "host_portnum:container_portnum"  # List of port mappings to expose from the docker
                                      # E.g. "8888:8888" for JupyterLab
 
# volume_mappings:
# - "host_path:container_path"        # List of volume mappings to mount from the host
                                      # E.g. "/path/to/host:/path/to/container"
 
# docker_extra_run_flags: "run flags" # Additional flags to pass to the `docker run` command

Common patterns — uncomment/add as needed:

3. test.sh (or test.py)

A quick smoke test that validates the package installed correctly. Should exit 0 on success, non-zero on failure.

Bash template (`test.sh`):

#!/bin/bash
 
# Copyright (C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT
 
echo "Running tests for <package_name>..."
<command_to_test_installation>
if [ $? -eq 0 ]; then
  echo "Tests passed!"
else
  echo "Tests failed!"
  exit 1
fi

Python template (`test.py`):

#!/usr/bin/env python3
# Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.
# SPDX-License-Identifier: MIT
import <package>
print(f"<package> version: {<package>.__version__}")
# Add a minimal functional check here

Guidelines:

• Keep it fast — just verify the install, don't run full test suites.
• Import the main module, print its version, maybe run one trivial operation.
• For services (like ollama), start the server, wait briefly, then test the endpoint.

4. README.md

Template:

# <Package Name> Docker Setup
 
Brief description of what this package provides and what it's useful for.
 
## Build & Run
 

ryzers build <package_name> ryzers run

 
## References
 
- <link to upstream project>
- <link to docs>
 
Copyright(C) 2026 Advanced Micro Devices, Inc. All rights reserved.

After Creating the Package

1. Update the main `README.md` — add a link to the new package in the "Supported Packages" table under the appropriate category row.

1. Test locally (if possible):

``bash ryzers build <package_name> ryzers run ``

Existing Categories

Create a new category directory if the package doesn't fit any of these.

Reference Examples

Study these existing packages for patterns:

• Minimal package: packages/init/ryzer_blank/ — bare minimum Dockerfile
• Typical package: packages/robotics/genesis/ — good all-around reference
• Service with ports: packages/llm/ollama/ — port mappings, volume mounts, server test
• Package with build args: packages/vision/opencv/ — uses ARG OPENCV_VERSION from config.yaml
• Web UI package: packages/ide/jupyterlab/ — port mapping, environment variables