Who is this for?
This is an introductory topic for embedded, edge, and cloud software developers who want to create their own Topo Projects to be natively deployed with Topo.
What will you learn?
Upon completion of this Learning Path, you will be able to:
- Explain the purpose and structure of a Topo Project
- Clone and deploy an existing Topo Project and modify it by adding new clone-time parameters
- Create a new Topo Project from a Docker Compose project
- Add x-topo metadata for configurable parameters, deployment guidance, and hardware requirements
- Locate and install Agent Skills to assist with creating and reviewing Topo Projects
Prerequisites
Before starting, you will need the following:
- Completion of the Deploy containerized workloads to Arm-based Linux targets with Topo Learning Path.
- 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 .
- Basic familiarity with containers and CLI tools
Summary
This summary was drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.
You’ll author and deploy Topo Projects to Arm-based Linux targets over SSH. First, you’ll clone and run a starter project to confirm your setup, then edit its
compose.yaml to add x-topo.parameters entries that make the greeting emoji configurable at clone time. Next, you’ll create a new project from an empty directory that serves a simple web page with configurable text and color while learning the core pieces of a project: standard Compose services, x-topo metadata, and build arguments for Arm Linux targets. You’ll also see where to find optional Agent Skills to assist with creating or converting projects, and how to recognize a successful deployment by observing the configured behavior on the target.Frequently asked questions
These FAQs were drafted with an approved AI-assisted workflow and reviewed by Arm contributors before publication. Human technical review remains part of the process so the final page reflects engineering rigor, accuracy, and Arm editorial standards.
You should see a new directory at the path you provided (for example,
~/topo-welcome) and clone output that includes lines like Copy files and Cloning into .... After cloning, the project’s services can be deployed to the Arm-based Linux target as shown in the steps.Add it under the
x-topo parameters section in compose.yaml, alongside the existing GREETING_NAME parameter. Define the parameter name and metadata there so Topo can surface it during cloning.Clone and deploy the updated project, then check the running service’s behavior for your change. For example, the Hello World greeting should include the emoji you configured, or the sample webpage should reflect your chosen text and color.
Include a
compose.yaml with standard Compose services, an x-topo metadata block, and project parameters wired to Docker build arguments when needed. The container image should be built for Arm Linux targets.Use Agent Skills as optional aids when you want help creating or converting a project into a Topo Project. Topo provides
topo-project-context for reference about x-topo and CLI behavior and topo-project-bootstrap to help convert a repository into a Topo Project.