Authoring Topo Projects

This guide details how to create Topo Projects for the Topo ecosystem.

File Structure

my-project/
├── compose.yaml   # REQUIRED: The definition file
├── Dockerfile     # Optional, but typical for Projects defining custom images
└── ...            # Any other files supporting the service, e.g. source code

The compose.yaml

You must extend the standard Compose Spec with x-topo metadata. In addition, all Project services must explicitly set platform: linux/arm64 so Implementations target Arm64. The only exception is for services deployed via remoteproc.

services:
  hello:
    platform: linux/arm64
    build:
      context: .
      # (Optional) defaults for plain docker compose; Implementations may override these from x-topo parameters
      args:
        GREETING: "Hello, World"

x-topo:
  name: "hello-world"
  description: |
    A simple Hello World service with a customizable greeting.
  # PROJECT PARAMETER DEFINITIONS
  # These enable interactive prompting behavior.
  parameters:
    GREETING:
      description: "The greeting message to display"
      required: true
      example: "Hello from Arm!"

The Dockerfile

Implementations pass arguments via standard Docker ARG directives.

FROM nginx:alpine

# 1. Consume the arg
ARG GREETING

# 2. Enforce requirement (Best Practice)
RUN test -n "$GREETING" || (echo "ERROR: GREETING project parameter is required" && exit 1)

# 3. Use the arg to create a simple HTML page
RUN echo "<h1>$GREETING</h1>" > /usr/share/nginx/html/index.html

---

3. The x-topo Schema Reference

The x-topo block must be placed at the root of your YAML file.

x-topo:
  name: string # Required
  description: string # Optional
  features: [string] # Optional
  deployment_success_message: string # Optional
  parameters: # Optional
    <PARAMETER_NAME>:
      description: string # Optional
      required: boolean # Optional
      example: string # Optional

Deployment success message

deployment_success_message supports standard Compose interpolation. Topo provides these additional variables when it displays the message:

• TOPO_TARGET: The complete SSH destination in URI form, such as ssh://user@board.local.
• TOPO_TARGET_HOSTNAME: The Target hostname resolved from the SSH configuration, such as board.local.

x-topo:
  name: "web-app"
  deployment_success_message: |
    Open http://${TOPO_TARGET_HOSTNAME:-localhost}:8080

---

4. Testing Your Project

Use the Topo CLI to verify your Projects locally.

# Verify build success
topo deploy --target root@some-ssh-target