diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/_index.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/_index.md new file mode 100644 index 0000000000..47a463f695 --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/_index.md @@ -0,0 +1,77 @@ +--- +title: Create your own Topo templates + +draft: true +cascade: + draft: true + +description: Create a Topo Template after your project to use Topo to deploy containerized workloads to Arm-based Linux targets over SSH. + +minutes_to_complete: 30 + +who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Templates projects to be natively deployed with Topo. + +learning_objectives: + - Install Topo and verify that the host and target environments are ready for deployment + - Run health checks and generate a target description to identify compatible Arm processor features and templates + - Clone a Topo template and deploy a containerized workload to an Arm-based Linux target + - (Optional) Deploy firmware and applications to heterogeneous Cortex-A + Cortex-M devices using remoteproc-runtime + +prerequisites: + - This learning path builds on [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/). + - A host machine (x86 or Arm) with Linux, macOS, or Windows + - An Arm-based Linux target accessible over SSH, for example an Arm-based Linux VM, Raspberry Pi, DGX Spark, or NXP i.MX 93 + - Docker installed on the host and target. For installation steps, see [Install Docker](/install-guides/docker/). + - lscpu installed on the target (pre-installed on most Linux distributions) + - Basic familiarity with containers and CLI tools + +author: Tomas Agustin Gonzalez Orlando + +### Tags +skilllevels: Introductory +subjects: Containers and Virtualization +armips: + - Neoverse + - Cortex-A + - Cortex-M +tools_software_languages: + - Topo + - Docker + - SSH +operatingsystems: + - Linux + - macOS + - Windows + +### Cross-platform metadata only +shared_path: true +shared_between: + - servers-and-cloud-computing + - laptops-and-desktops + - embedded-and-microcontrollers + +further_reading: + - resource: + title: Topo template format + link: https://github.com/arm/topo-template-format + type: documentation + - resource: + title: Topo repository + link: https://github.com/arm/topo + type: documentation + - resource: + title: Topo releases + link: https://github.com/arm/topo/releases/latest + type: website + - resource: + title: remoteproc-runtime + link: https://github.com/arm/remoteproc-runtime + type: documentation + + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/_next-steps.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/_next-steps.md new file mode 100644 index 0000000000..727b395ddd --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # The weight controls the order of the pages. _index.md always has weight 1. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/creating-a-new-template.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/creating-a-new-template.md new file mode 100644 index 0000000000..184fc63b3a --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/creating-a-new-template.md @@ -0,0 +1,294 @@ +--- +title: Creating a new Topo Template +weight: 5 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Create a Topo Template from scratch + +You have already cloned and modified an existing Topo Template. In this section, you will create a new Template from an empty directory. + +The Template you create serves a small web page with configurable text and color. It demonstrates the core parts of a Topo Template: + +- A `compose.yaml` file with standard Compose services +- An `x-topo` metadata block +- Build arguments exposed as Topo clone-time parameters +- A container image built for Arm Linux targets + +### Create the project directory + +Create a new directory for the Template: + +```bash +mkdir -p ~/topo-template-work/topo-message-card/src +cd ~/topo-template-work/topo-message-card +``` + +A Topo Template is a normal project directory. At minimum, it must contain a `compose.yaml` file. Most Templates also include a `Dockerfile` and application source code. + +The directory you create in this section will have the following structure: + +```output +topo-message-card/ +├── compose.yaml +├── Dockerfile +├── README.md +└── src/ + └── index.html +``` + +### Create the web page + +Create the application HTML file: + +```bash +cat > src/index.html <<'EOF' + + + + + + {{CARD_TITLE}} + + + +
+

{{CARD_TITLE}}

+

{{CARD_MESSAGE}}

+
+ + +EOF +``` + +The values wrapped in double braces are placeholders. The `Dockerfile` replaces them with values supplied by Topo. + +### Create the Dockerfile + +Create a `Dockerfile`: + +```bash +cat > Dockerfile <<'EOF' +FROM nginx:alpine + +COPY src/index.html /usr/share/nginx/html/index.html + +ARG CARD_TITLE="Hello from Topo" +ARG CARD_MESSAGE="This page was created from a Topo Template." +ARG ACCENT_COLOR="#0091bd" + +RUN sed -i "s|{{CARD_TITLE}}|${CARD_TITLE}|g" /usr/share/nginx/html/index.html +RUN sed -i "s|{{CARD_MESSAGE}}|${CARD_MESSAGE}|g" /usr/share/nginx/html/index.html +RUN sed -i "s|{{ACCENT_COLOR}}|${ACCENT_COLOR}|g" /usr/share/nginx/html/index.html +EOF +``` + +Topo passes configuration values to templates through Docker build arguments. The `ARG` lines define the values consumed during the image build. + +### Create the compose file + +Create `compose.yaml`: + +```bash +cat > compose.yaml <<'EOF' +# yaml-language-server: $schema=https://raw.githubusercontent.com/arm/topo-template-format/refs/heads/main/schema/topo-template-format.json +services: + message-card: + platform: linux/arm64 + build: + context: . + args: + CARD_TITLE: "Hello from Topo" + CARD_MESSAGE: "This page was created from a Topo Template." + ACCENT_COLOR: "#0091bd" + ports: + - "8088:80" + +x-topo: + name: "Message Card" + description: | + A minimal web application Template that shows a configurable title, + message, and accent color. + type: "application" + deploy_success_message: | + Message Card is running. Open http://localhost:8088/ in your browser. + args: + CARD_TITLE: + description: "The title to show on the message card" + required: true + example: "Hello from Arm" + CARD_MESSAGE: + description: "The message to show below the title" + required: false + default: "This page was created from a Topo Template." + example: "Built once and deployed with Topo" + ACCENT_COLOR: + description: "The CSS color used for the card accent" + required: false + default: "#0091bd" + example: "#00a3a3" +EOF +``` + +This file is both a Compose file and a Topo Template definition. + +The `services` section is standard Compose. The service builds the local `Dockerfile`, publishes the web server on port `8088`, and sets `platform: linux/arm64` so the service targets Arm-based Linux systems. + +The `x-topo` section is the Topo metadata block: + +- `name` gives the Template a human-readable name. +- `description` explains what the Template does. +- `type` identifies this as an application Template. +- `deploy_success_message` prints a useful hint after deployment. +- `args` defines the values Topo prompts for when someone clones the Template. + +The argument names in `x-topo.args` match the keys under `services.message-card.build.args`. When Topo resolves the arguments, it writes the selected values into the build arguments. + +### Add a README + +Create a short `README.md`: + +````bash +cat > README.md <<'EOF' +# Message Card + +This project is a Topo Template. It builds a small Nginx web application for +Arm Linux targets. + +## Usage + +```bash +topo clone dir:/path/to/topo-message-card +cd topo-message-card +topo deploy --target localhost +``` + +Open `http://localhost:8088/` in your browser after deployment. +EOF +```` + +The README is not required by the Template format, but it is useful when you share the Template with other users. + +### Clone the local Template + +Move to the parent directory and clone your local Template with Topo: + +```bash +cd .. +topo clone dir:./topo-message-card ./message-card-demo \ + CARD_TITLE="Hello from Arm" \ + CARD_MESSAGE="Created from a new Topo Template" \ + ACCENT_COLOR="#00a3a3" +``` + +You can also omit the argument values and answer the interactive prompts: + +```bash +topo clone dir:./topo-message-card ./message-card-demo +``` + +If `./message-card-demo` already exists, remove it or choose a different output directory before cloning again. + +After cloning, inspect the generated project: + +```bash +cd message-card-demo +sed -n '1,80p' compose.yaml +``` + +The `build.args` values should contain the values you provided: + +```yaml +services: + message-card: + platform: linux/arm64 + build: + context: . + args: + CARD_TITLE: "Hello from Arm" + CARD_MESSAGE: "Created from a new Topo Template" + ACCENT_COLOR: "#00a3a3" +``` + +### Deploy the new project + +Deploy the cloned project to the host machine: + +```bash +topo deploy --target localhost +``` + +When deployment completes, open `http://localhost:8088/` in your browser. + +Confirm that the container is running: + +```bash +topo ps --target localhost +``` + +The output should include the `message-card` service and port `8088`. + +### Add hardware requirements + +Only add `features` when your Template needs specific Arm hardware features. For example, a SIMD benchmark that requires SVE can declare: + +```yaml +x-topo: + name: "SIMD Visual Benchmark" + description: | + Visual demonstration of SIMD performance benefits on Arm processors. + type: "application" + features: + - "SVE" +``` + +Topo can use these feature requirements when listing Templates against a target. + +### Share the Template + +To share your Template, publish the Template directory as a Git repository. Other users can then clone it with Topo: + +```bash +topo clone https://github.com//topo-message-card.git +``` + +If the Template is intended to be reusable by the wider Topo community, include: + +- `compose.yaml` +- Any Dockerfiles and source files required by the services +- A `README.md` with usage instructions +- A license file +- Clear `x-topo` metadata and argument descriptions + +You now have a complete Topo Template created from scratch. diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/hello-world-template.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/hello-world-template.md new file mode 100644 index 0000000000..a94d259cb6 --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/hello-world-template.md @@ -0,0 +1,149 @@ +--- +title: Clone Topo Hello World, deploy and modify it +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Clone and deploy the Hello World Template + +### List Topo Templates + +List the available Topo Templates from the curated list in Topo: + +```bash +topo templates +``` + +The output should be similar to the following, the Hello World template should be present: + +```output +Hello World | https://github.com/Arm-Examples/topo-welcome.git | main + A minimal "Hello, World" web app for validating a Topo setup and deployment. + It runs a single service that exposes a web page on the target, + with the greeting text customizable via the GREETING_NAME parameter. + +Lightbulb Moment | https://github.com/Arm-Examples/topo-lightbulb-moment.git | main + Features: remoteproc-runtime + Reads a switch over GPIO pins on an M class cpu, reports switch state over + Remoteproc Message, then a web application on the A class reads this and + displays a lightbulb in either the on or off state. The lightbulb state is + described by an LLM in any user-specified style. + +(...) +``` + +### Clone the Hello World template + +```bash +topo clone https://github.com/Arm-Examples/topo-welcome.git +``` + +The output should be similar to the following. You will be prompted for configuration arguments: + +```output +┌─ Copy files ────────────────────────────────────────── +Cloning into 'topo-welcome'... +remote: Enumerating objects: 12, done. +remote: Counting objects: 100% (12/12), done. +remote: Compressing objects: 100% (9/9), done. +remote: Total 12 (delta 0), reused 8 (delta 0), pack-reused 0 (from 0) +Receiving objects: 100% (12/12), 62.64 KiB | 2.61 MiB/s, done. + +┌─ Input args ────────────────────────────────────────── +Provide: The text to use in the greeting message +Example: Markus +Default: World +GREETING_NAME (required)> +``` + +You can fill the GREETING_NAME with your own name of press Enter to choose the defaults. +You will then see something similar to the following output: + +```output +┌─ Project ready ─────────────────────────────────────── +Created in 'topo-welcome' + +Now run: + cd topo-welcome + topo deploy +``` + +### Prepare the host machine for emulation + +Topo Templates are meant to be deployed to Arm-based Linux targets. In this learning path, we are going to be deploying to your host machine. If your machine is an x86 machine, you may need to install an arm64 emulator, such as: + +```bash +docker run --privileged --rm tonistiigi/binfmt --install arm64 +docker run --rm --platform linux/arm64 alpine uname -m +``` + +The expected output should be: + +```output +aarch64 +``` + +### Deploy the template to localhost + +You can now deploy the project to the host/build machine: + +```bash +cd topo-welcome +topo deploy --target localhost +``` + +Wait for the build and deploy to complete. The expected output is similar to: + +```output +$ topo deploy --target localhost +10:52:52 WRN registry transfer is not yet supported with this configuration. Falling back to direct transfer. + +┌─ Build images ──────────────────────────────────────── +[+] Building 6.4s (11/11) FINISHED + => [internal] load local bake definitions 0.0s + => => reading from stdin 654B 0.0s + => [internal] load build definition from Dockerfile 0.0s + => => transferring dockerfile: 223B 0.0s + => [internal] load metadata for docker.io/library/nginx:alpine 1.4s + => [internal] load .dockerignore 0.1s + => => transferring context: 2B 0.0s + => [internal] load build context 0.1s + => => transferring context: 3.76kB 0.0s + => [1/3] FROM docker.io/library/ + (...) + + [+] build 1/1 + ✔ Image topo-welcome-app Built 6.4s + +┌─ Pull images ───────────────────────────────────────── + +┌─ Start services ────────────────────────────────────── +[+] up 2/2 +┌─ Deployment Success ────────────────────────────────── 0.1s +Run `topo ps` to see deployed containers 0.2s +``` + +Confirm that the container is running correctly: + +```bash +topo ps +``` + +The output should be similar to: + +```output +Image Status Processing Domain Address +topo-welcome-app Up Less than a second Linux Host localhost:8000, [::]:8000 +``` + +### Visualize the application + +Open your browser on `http://localhost:8000/`, you should see the Hello World application running. + + +The Hello World application appears as follows: + + +![Screenshot of the Hello World web interface running on localhost. This confirms successful deployment and provides a visual reference for the expected result.#center](topo_hello_world.png "Hello World web interface on localhost") diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/modified_template.png b/content/learning-paths/cross-platform/create-your-own-topo-templates/modified_template.png new file mode 100644 index 0000000000..9c9e01b306 Binary files /dev/null and b/content/learning-paths/cross-platform/create-your-own-topo-templates/modified_template.png differ diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/modifying-hello-world.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/modifying-hello-world.md new file mode 100644 index 0000000000..46a4e39783 --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/modifying-hello-world.md @@ -0,0 +1,162 @@ +--- +title: Modifying the Hello World Template +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Modify the Hello World Template + +In the previous section, you cloned and deployed the Hello World Template. In this section, you will modify the template so the greeting emoji can be configured when someone clones the template. + +### Add a new template argument + +Open the Hello World Template `compose.yaml` file: + +```bash +cd topo-welcome +``` + +Find the `x-topo.args` section. It currently contains the `GREETING_NAME` argument: + +```yaml +args: + GREETING_NAME: + description: The text to use in the greeting message + required: true + default: "World" + example: "Markus" +``` + +Add a new `GREETING_EMOJI` argument below `GREETING_NAME`: + +```yaml +args: + GREETING_NAME: + description: The text to use in the greeting message + required: true + default: "World" + example: "Markus" + GREETING_EMOJI: + description: The emoji to show next to the greeting + required: false + default: "🐳" + example: "🚀" +``` + +This adds a second clone-time parameter. The argument is optional, so users can press Enter to accept the default whale emoji. + +### Pass the emoji to the build + +In the same `compose.yaml` file, find the service build arguments: + +```yaml +services: + app: + build: + context: . + args: + GREETING_NAME: World +``` + +Add `GREETING_EMOJI` to the build arguments: + +```yaml +services: + app: + build: + context: . + args: + GREETING_NAME: World + GREETING_EMOJI: "🐳" +``` + +This makes the emoji available to the `Dockerfile` when Topo builds the application image. + +### Replace the hard-coded emoji + +Open the HTML file used by the web application. Find the line with the hard-coded emoji: + +```html +🐳 +``` + +Replace it with the `GREETING_EMOJI` template variable: + +```html +{{GREETING_EMOJI}} +``` + +Topo replaces `{{GREETING_EMOJI}}` with the value provided during `topo clone`. + +### Update the Dockerfile + +Open the `Dockerfile`. It currently defines `GREETING_NAME` as a build argument and uses `sed` to replace the `{{GREETING_NAME}}` placeholder: + +```dockerfile +ARG GREETING_NAME="World" + +RUN sed -i "s|{{GREETING_NAME}}|${GREETING_NAME}|" /usr/share/nginx/html/index.html +``` + +Add a `GREETING_EMOJI` build argument, then add a second `sed` command to replace the `{{GREETING_EMOJI}}` placeholder: + +```dockerfile +FROM nginx:alpine + +COPY src/index.html /usr/share/nginx/html/index.html + +ARG GREETING_NAME="World" +ARG GREETING_EMOJI="🐳" + +RUN sed -i "s|{{GREETING_NAME}}|${GREETING_NAME}|" /usr/share/nginx/html/index.html +RUN sed -i "s|{{GREETING_EMOJI}}|${GREETING_EMOJI}|" /usr/share/nginx/html/index.html +``` + +### Clone the modified template + +Create a new directory for a fresh clone of your modified local template: + +```bash +mkdir ../newdir/ +``` + +Clone the local template into the new directory: + +```bash +topo clone dir:/home/tomgon01/eco/topo/playground/topo-welcome ../newdir/topo-welcome +``` + +Topo prompts for the configured template arguments. You should now see prompts for both `GREETING_NAME` and `GREETING_EMOJI`. Use the example values, do not accept the defaults. When cloning completes, Topo creates the new project in `../newdir/topo-welcome`: + +```output +┌─ Copy files ────────────────────────────────────────── + +┌─ Input args ────────────────────────────────────────── +Provide: The text to use in the greeting message +Example: Markus +Default: World +GREETING_NAME (required)> + +Provide: The emoji to use in the greeting message +Example: 🚀 +Default: 🐳 +GREETING_EMOJI (required)> 🚀 +``` + +### Deploy the modified Template + +```bash +cd ../newdir/topo-welcome +topo deploy --target localhost +``` + +### Visualize the application + +Open your browser on `http://localhost:8000/`, you should see the modified Hello World application running. + +The Hello World application appears as follows: + + +![Screenshot of the modified Hello World web interface running on localhost. This confirms successful modification and deployment and provides a visual reference for the expected result.#center](modified_template.png "Hello World web interface on localhost") diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/overview.md b/content/learning-paths/cross-platform/create-your-own-topo-templates/overview.md new file mode 100644 index 0000000000..78f2d213e4 --- /dev/null +++ b/content/learning-paths/cross-platform/create-your-own-topo-templates/overview.md @@ -0,0 +1,50 @@ +--- +title: Topo Template introduction +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Get started + +Before getting started, you should complete the Learning Path [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) to learn about Topo, why to use it, how to install it and how to use it for target inspection, listing templates and deployment. + +## What is Topo? + +[Topo](https://github.com/arm/topo) is an open-source command-line tool developed by Arm used to deploy projects to an Arm-based Linux target over SSH. Topo builds container images on the host, transfers them to the target, and starts the services on the target. Topo can also build and deploy directly on the target. + +## What is a Topo Template? + +A Topo Template is a containerized sample project for Arm-based Linux systems. At minimum, it is a directory containing a compose.yaml, Dockerfiles, and source code, with an x-topo metadata block that describes what the Template does, what hardware features it requires, and what parameters a user can configure. + +The [Topo Template Format Specification](https://github.com/arm/topo-template-format) is based on the [Compose Specification](https://github.com/compose-spec/compose-spec), extended with `x-topo` metadata that describes requirements such as CPU features and build arguments. The Compose Specification is a standard, YAML-based format for describing multi-container applications. Instead of starting containers individually, you define all services, images, connections, and configuration in a single `compose.yaml` file. + +In this learning path, you'll learn how to create and modify your own Topo Template. + +## Where can I find Topo Templates? + +Because the Topo Templates specification is an open one, anyone can publish their own Topo Templates and any tool can read and act on x-topo metadata to discover, validate, and deploy Templates. + +A curated list of example Templates can be found either via: + +1. the [topo templates](https://github.com/arm/topo?tab=readme-ov-file#3-find-a-template) command or +2. the [topo catalog](https://github.com/arm/topo/blob/main/internal/catalog/data/templates.json). + +If you create your own Template, you can [Propose Your Template to Topo](https://github.com/arm/topo-template-format#propose-your-template-to-topo) + +## Why create a Topo Template? + +Creating a Topo Template allows you to inject the `x-topo` metadata on top of your docker compose project with extra information to the Docker Compose spec such as: + +1. Build arguments +2. Hardware requirements (features like SVE or NEON or required RAM). +3. Project configuration at Topo clone time. + +You can then share your Topo Template with the community, who will be able to deploy your project via Topo or any other tool that supports the Topo Template Format Specification. + +## What you've accomplished and what's next + +You have now installed Topo on your host and confirmed it is available. +You have got an understanding of what a Topo Template is and what its purpose is. +Next, you'll clone your first template and modify it. diff --git a/content/learning-paths/cross-platform/create-your-own-topo-templates/topo_hello_world.png b/content/learning-paths/cross-platform/create-your-own-topo-templates/topo_hello_world.png new file mode 100644 index 0000000000..100d5fbe02 Binary files /dev/null and b/content/learning-paths/cross-platform/create-your-own-topo-templates/topo_hello_world.png differ