Deploying a Container
This section covers the process of deploying containers to Atym-enabled devices. While the Quickstart Guide provides a simple introduction to deployment, this Developer Guide walks you through each step of the deployment process in detail, as well as some quality of life improvements to help streamline your development workflow.
By default, Atym containers run in interpreted mode, where the WebAssembly binary is executed at runtime by the Atym runtime's interpreter. This works out of the box on all supported devices.
For production or performance-sensitive workloads, Atym supports Ahead-of-Time (AOT) compilation, which pre-compiles your container's WebAssembly binary into native machine code for a specific target architecture, delivering near-native execution speeds. See the Deploying with AOT section below for instructions.
Deployment Process Overview
Deploying an Atym container involves two primary steps:
Pushing Containers to the Atym Hub
After building your application, you'll need to push it to the Atym Hub to make it available for deployment to devices.
1. Push the Container to Atym Hub
Before pushing your container to the Atym Hub ensure that you're logged in using the atym login command.
Use the atym push command to upload your container:
atym push your-project
Your container image name should correspond to the name defined in your build.yaml file, in our case that is your-project.
For versioned containers, you can add a tag:
atym push your-project:v1.0
If no tag is specified, Atym automatically assigns the "latest" tag to your container.
Additionally, you can add a description to your container with the -d flag:
atym push your-project:v1.0 -d "Version 1.0 release"
2. Verify the Push was Successful
Locally
After running pushing your container to the Atym Hub you should see output similar to:
$ atym push your-project:v1.0 -d "Version 1.0 release"
Image Filename: /home/demo_user/.atym/your-project
Reference: your-project
Tag: v1.0
Uploading image file...
Image file uploaded successfully
This confirms that your container was successfully uploaded to the Atym Hub.
In The Atym Hub
You can also verify that the container was uploaded successfully to the Atym Hub via the atym list repositories command like so:
atym list repositories
You should see an output listing your-project in your default repository like so:
[
"blinky",
"hello-world",
"your-project"
]
Lastly, if you've uploaded multiple different image tags you can check all available tags by issuing the atym list images like so:
atym list images your-project
You should then see an output listing all tags for the your-project container like so:
[
"latest",
"v1",
"v2",
"v3"
]
Running Containers on Devices
After your container is available in the Atym Hub, you can deploy it to your target device.
1. Identify Your Target Device
Before deploying, you need to identify the device you want to deploy to. You can list your available devices using the atym list devices command like so:
atym list devices
Note either the deviceName or deviceUUID for device you want to deploy to.
You will need to login to the Atym Hub via atym login before being able to run most commands, including the atym list devices command.
2. Deploy the Container to Your Device
Use the atym run command to deploy your container:
atym run your-project-name-on-device your-project -n myDevice
Where:
your-project-name-on-deviceis the name you want to give to the container instance on the deviceyour-projectis the container image name you pushed to the Atym Hub-nfollowed bymyDeviceis thedeviceName(or "name") of your target device
If you frequently deploy to the same device, check out the Default Device Configuration guide to set up default devices. This eliminates the need to specify your deviceName or deviceUUID in every command!
Alternative: Deploy a Specific Container Version
For deploying a specific version (v1.0 in this example) run the following:
atym run your-project-name-on-device your-project:v1.0 -n myDevice
Alternative: Deploy Multiple Containers
You can deploy multiple containers in a single command like so:
atym run container1 image1:tag1 container2 image2:tag2 container3 image3:tag3 -n myDevice
Alternative: Deploy Using deviceUUID
For deploying containers to your device via the deviceUUID, rather than the deviceName run the following:
atym run your-project-name-on-device your-project -d ffffeeee-1234-5678-90ab-cdefabcdefab
Where:
-dfollowed byffffeeee-1234-5678-90ab-cdefabcdefabis thedeviceUUIDof your target device
3. Verify the Container is Running
After deploying your container, you'll need to verify the container has ran successfully. You can do this one of two ways:
Via the Console
With your board connected to your serial console, you should see your program emit some sort of output once you have successfully ran it. The output for our bare bones "your-project" source file looks like this:
atym:~$ Client connected.
Your Project
Via the CLI
You can also verify the container has loaded and ran on your device by using the atym list containers command like so:
atym list containers ffffeeee-1234-5678-90ab-cdefabcdefab
Where:
ffffeeee-1234-5678-90ab-cdefabcdefabis yourdeviceUUID
If successful, you should see similar output to this in your terminal:
Containers defined for device: ffffeeee-1234-5678-90ab-cdefabcdefab
{
"containers": [
{
"name": "your-project",
"resources": [
{
"type": 1,
"sha256": "sha256:71cb138990af175c4baf0c43361e5c055ed60a5d2632ee547597be56dcfa07e2",
"size": 2397
}
]
}
]
}
Understanding the Deployment Process
In summation, the Atym deployment process moves your container from local development to execution on a target device. This process includes:
- Container Distribution: The
atym pushcommand uploads your locally built container to the Atym Hub, making it available to all authorized devices in your tenant. - Container Instantiation: The
atym runcommand instructs the Atym Hub to deploy your container to your specified device, where it is then downloaded and instantiated by the Atym runtime. - Result: The container runs on your target device with access to the device capabilities defined in your container configuration. The same container can be deployed to multiple devices or updated with new versions over time.
Deploying with AOT
AOT (Ahead-of-Time) compilation pre-compiles your container's WebAssembly binary into native machine code for a specific device architecture, enabling near-native execution performance.
Deploying with AOT requires three steps, in order:
Step 1: Push the Container with an AOT Configuration
Create an AOT configuration file (e.g. aot.yaml) for your target architecture, then push the container with it so the Atym Hub can transpile the binary:
atym push your-project:v1.0 -a aot.yaml
Alternatively, you can specify the target inline using atym add aot:
atym add aot your-project:v1.0 -c cortex-m4 -t thumbv8m.base -a eabihf
Step 2: Enable AOT on the Device
Enable AOT on your target device so the Hub knows to deploy the AOT-compiled image:
atym update device <deviceUUID> --aot true --target thumbv8m.base
Step 3: Deploy the Container
Deploy the container as usual using atym run. The Hub will automatically select the AOT image for your device:
atym run your-project-name-on-device your-project:v1.0 -n myDevice
For full details on AOT configuration options, architecture parameters, and how to enable/disable AOT per device, see the AOT Compilation reference.
Troubleshooting Deployments
Below are common errors you might encounter when deploying containers and their likely solutions:
| Error Message | Possible Cause | Solution |
|---|---|---|
| 400 Bad Request:
| Incorrect device UUID provided | Verify your device UUID with atym list devices and ensure you're using the correct UUID in your command |
| Update Error:
| Wrong image name or tag used | Double-check the image name and tag, and verify that the container exists in your Atym Hub repository |