Deployment Workflow

Complete guide to building application container images and deploying to Sol3 hardware.

Prerequisites

Completed Getting Started
Completed SSH Setup
Completed Development Workflow

Overview

The deployment workflow creates containerized applications that run on Sol3 devices:

Build Application Image - Create a Docker container with your application and dependencies
Deploy to Device - Push the container image to the device
Run Application - Start the containerized application on the device

Building Application Images

The SDK provides the sol3_build_app_image script to create deployable container images.

Build for Sol3 Hardware (ARM64)

# Build for Sol3 device
sol3_build_app_image my-app arm64 --cmake-preset arm64

# Build with custom tag
sol3_build_app_image my-app arm64 --cmake-preset arm64 --tag v1.0.0

Important

While there is a distinction between the “arch” (the architecture Docker uses to build the image) and “preset” (the CMake preset which configures the build for direct or cross-compilation), they are related. Builds must use a consistent arch/preset pair, otherwise the build will fail.

Build for Testing (x64)

Build x64 images for testing on your development machine:

# Build for x64 testing
sol3_build_app_image my-app x64 --cmake-preset x64

# Run locally to test (same mounts/privileged as on-device; see below)
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  my-app-x64:latest

Tip

If possible, test your application in a container on x64 before deploying to ARM64 hardware. This catches build/containerization issues early.

Understanding the Multi-Stage Build

The sol3_build_app_image script uses your project’s Dockerfile, which inherits the SDK’s multi-stage build system:

Base Stage - System dependencies and sysroot
Build Stage - Build tools, CMake, vcpkg, compilation
Runtime Stage - Application binary and runtime dependencies only

See the Dockerfile Architecture for details.

Image Naming Convention

Images are named following this pattern:

<app-name>-<preset>:<tag>

Examples:

my-app-arm64:latest - Latest ARM64 build
my-app-arm64:v1.0.0 - Versioned ARM64 release
my-app-x64-debug:latest - Latest x64 debug build for testing

Deploying to Sol3 Devices

Deploy Application

Use the sol3_deploy_app_image script to deploy images to the device. The script handles the entire deployment process automatically:

# Deploy application (basic usage)
sol3_deploy_app_image my-app-arm64:latest <USER@HDK_IP>

# Deploy specific version
sol3_deploy_app_image my-app-arm64:v1.0.0 <USER@HDK_IP>

How Deployment Works

The sol3_deploy_app_image script streams the image directly to the device over SSH:

Validates Local Image - Checks that the image exists locally
Tests SSH Connectivity - Verifies SSH access to the device
Transfers Image - Pipes docker save | gzip into docker load on the device over SSH

The device does not need network access or a running registry. The image lands in the device’s Docker daemon under its original name and tag. The script provides progress feedback and detailed error messages if any step fails.

Prerequisites

Before deploying, ensure:

SSH Access: Passwordless SSH access to the device (SSH keys configured)
Image Built: The application image exists locally

Deployment Output

Successful deployment shows:

Checking if image exists locally (my-app-arm64:latest)... ✓
Testing SSH connectivity to <USER@HDK_IP>... ✓
Transferring my-app-arm64:latest to <USER@HDK_IP> (docker save | ssh docker load)
✅ Image deployed successfully!
   Image:  my-app-arm64:latest
   Device: <USER@HDK_IP>

To run on device:
   docker run -t -v /run/sol3:/run/sol3 -v /dev:/dev --privileged my-app-arm64:latest [ARGS]

Run Application on Device

When running on the device via docker run, you must ensure that both the /run/sol3 and /dev directories are bind-mounted into the container, and it also must be run in --privileged mode. These ensure that ShmemExchange will work as expected. Other than those requirements, feel free to format the docker run command as needed to support your application:

ssh <USER@HDK_IP>
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  my-app-arm64:latest <ARGS>

Complete Deployment Example

# Build for ARM64
sol3_build_app_image my-app arm64 --cmake-preset arm64 --tag v1.0.0

# Deploy to device
sol3_deploy_app_image my-app-arm64:v1.0.0 <USER@HDK_IP>

# Run on device
ssh <USER@HDK_IP>
docker run --rm \
  -v /run/sol3:/run/sol3 \
  -v /dev:/dev \
  --privileged \
  --name my-app \
  my-app-arm64:v1.0.0