Skip to main content

Getting started

After you install Topo, use this guide to check a target, discover a compatible Topo Project, and deploy the project.

note

The commands in this guide use pi@raspberrypi as the target. Replace this value with the SSH destination for your target. Topo accepts an SSH alias, a value such as user@host, or a URL such as ssh://user@host:2222.

Check the host and target​

Run the health checks:

topo health --target pi@raspberrypi

Topo checks the required host tools, SSH connection, target container engine, and target hardware. Resolve all errors and review each warning. When available, the report includes commands to correct problems.

If the target host key is unknown, confirm the target identity. Then run the suggested command to accept the key. If public-key authentication is not configured, run the following command after you accept the host key:

topo setup-keys --target pi@raspberrypi

This command creates a dedicated key, copies the public key to the target, and updates your SSH configuration. The target must permit password authentication for the initial key transfer. If it does not, configure a public key through your existing device management process.

Run topo health again and confirm that no checks report an error. You can ignore a Remoteproc Runtime warning if you do not plan to deploy firmware to a remote processor.

Find a compatible Topo Project​

List the available projects and check their compatibility with the target hardware:

topo projects --target pi@raspberrypi

The output includes a clone command for each project.

Clone and configure a project​

Clone the project:

topo clone https://github.com/Arm-Examples/topo-welcome.git

When you run the topo clone command, Topo prompts for values that configure the project. You can also pass values through the command line or a configuration file.

Deploy the project​

Change to the project directory and deploy it:

cd topo-welcome
topo deploy --target pi@raspberrypi

Topo builds or pulls the images on the host, transfers them to the target, and starts the services. Run commands that manage the deployment from the project directory. These commands use the compose.yaml file in the current directory.

Verify the deployment​

List the running containers for the project:

topo ps --target pi@raspberrypi

Check the Address column in the topo ps output for accessible service endpoints.

After you change the project, run topo deploy --target pi@raspberrypi again. Docker and Topo reuse cached layers where possible to reduce deployment time.

Stop the deployment​

From the project directory, stop the services:

topo stop --target pi@raspberrypi

This command stops the services but does not remove their containers.

Next steps​