Deploy an app to the edge in under 10 minutes
What you will accomplish
By the end of this guide, you will be able to make deployable Darcy AI application packages that will run on any hardware that meets the requirements for Darcy AI. The list of compatible hardware is extensive, allowing you to deploy your Darcy AI applications to the devices that fit your solution needs.
- Docker Desktop and a Docker account
- Darcy Cloud account (Free)
- An edge device
- Video camera attached to the camera port
- AI Processor
: Google Coral edge TPU (USB version attached to USB 3.0 port)
- CPU Processing can be used with varying performance.
- Power supply : 5.1V * 3.5A
- Micro SD card with at least 16GB capacity (32GB+ recommended)
- Internet connectivity
Package your app
Install Docker and create an account
- Install Docker Mac or Windows (coming soon)
- Create a Docker Hub Account
dockercommands in terminal. You will be using these commands to package your Darcy AI applications for deployment, including deploying to edge devices that are a different CPU architecture than your computer! To make sure you can use the latest Docker build commands like
buildxyou can add an environment variable to your computer with the following command
export DOCKER_CLI_EXPERIMENTAL=enabled. This will tell Docker to allow use of the latest tools which will save you a lot of time when packaging your apps!
sudo dockerinstead of just
dockerdepending on how you install and set up Docker for Mac. If that is the case on your development machine, you can just add
sudoto the beginning of any
dockercommands shown in these guides.
Add a Dockerfile
To build your Darcy AI application container, you only need your Python file and a Dockerfile. A
Dockerfile is just a text file with the specific name
Dockerfile that tells the Docker command
tools how to make your containers. You can include as many files as you want in your container. The
commands for adding those files are discussed below.
FROM darcyai/darcy-ai-coral:dev RUN python3 -m pip install darcyai COPY ./YOURFILE.py /src/app.py CMD python3 -u /src/app.py
FROM command tells Docker which
to use. It will build your application container
starting from the base image.
RUN command tells Docker to execute a step. In the example above, the step is to install
darcyai Python library. We don’t include that library in the base image because that would
make it more difficult to use the latest Darcy AI library. Using this single command in your
Dockerfile, you will always get the latest Darcy AI library when building your container images.
COPY command tells Docker to take something from your local environment and make
a copy of it in your container. Use this command to copy in files that are part of your application,
such as .mp4 videos, .tflite
, and additional Python code files. The first part of the
command is the source and the second part is the destination. In the example above,
YOURFILE.py file is copied into the
/src/ directory in the container and renamed to
CMD command tells Docker to execute this command when the container is started. This is
different than the
RUN command which tells Docker to execute the command while building the
CMD statement is found at the end because the container must be fully built before
this statement. When the container starts, the instructions found after the
CMD will be executed.
In the example above, the instructions are to run the
/src/app.py Python file using
we have added the
-u parameter which tells the Python3 engine to use unbuffered output because we
want to see the output in the container logs unhindered.
Create a builder namespace for your build process
docker buildx command line tool that was installed with your Docker Desktop will allow you to
build and package container images for several target device platforms (CPU architectures) at the
same time. If you do not have the
docker buildx tool installed, you can learn about it and install
it from the
Docker BuildX Guide
The first step is to create a named builder that BuildX can use. You can do that with the following command. Replace YOURNAME with the name you would like to use.
NOTE: If your installation of Docker Desktop requires you to use
sudo when using
commands, simply add the
sudo to the beginning of everything shown in this guide.
docker buildx create --name YOURNAME
And now that you have created a builder namespace, let’s set BuildX to use that namespace with this command.
docker buildx use YOURNAME
Build your Docker container
Now that you have a working BuildX builder namespace and a Dockerfile in your current working directory where your Python file is located, you can do the actual build.
NOTE: If you don’t already have an account, create one now at https://hub.docker.com . You will be given an organization which is your username. Ensure that you are logged into your Docker Hub account using the following command by replacing the organization with your Docker Hub organization name.
docker login --username=organization
Run the following command in the directory of your Dockerfile to perform the build. You will
need to replace
organization with your actual Docker Hub organization name. Also replace
application-name with the name you want to use for this container. The part after the
is the tag. You can put anything you want here. It is a common practice to put a version number,
1.0.0 in the example below.
docker buildx build -t organization/application-name:1.0.0 --platform linux/amd64,linux/arm64,linux/arm/v7 --push .
--platform part of this build command specifies the platforms for which you want containers
built. It is recommended to build for the list of platforms shown in the example here. This will
allow you to run your Darcy AI application container on 64-bit x86 devices and both 64-bit and
32-bit ARM devices.
--push part of the command tells Docker to upload your container images to Docker Hub when it
is finished building.
Don’t forget the
. on the end of the command. That tells the BuildX tool to look for
Dockerfile in the current directory.
Your build process may take 10 or 15 minutes if you are building for the first time and you do not have a very fast internet connection. This is because the underlying container base images will need to be downloaded. After the first build, this process should only take a few minutes. You can watch the output of the command to see the build progress. A separate container image will be built for each of the platforms specified in the command. Additionally a container manifest file will be created and added to the container registry (Docker Hub) so different platforms will know which image to download and start.
Make sure your Darcy AI application container is available
In the packaging process above, you specified a full application container identifier for your Darcy AI
application. This identifier consists of an organization name followed by a
/ and then a container
name followed by a
: and then a tag. As an example, the identifier
darcyai/darcy-ai-explorer:1.0.0 represents an application called
with a tag
1.0.0 that is hosted under the Docker Hub organization
You will use your container identifier in your application deployment YAML file below. Make sure your container images were successfully pushed to Docker Hub at the conclusion of your packaging process.
Deploy your app
Add your devices to the Darcy Cloud
The Darcy Cloud gives you management of all your edge devices and edge applications in one place. You can open an SSH shell session on demand, deploy applications, and see the health and status for every device. All of this functionality works no matter where your edge devices are physically located, even when they are behind NAT layers and firewalls. Use the Darcy Cloud to make building, deploying, and debugging easier, and then use it to operate your edge AI applications in production systems.
If you don’t already have an account, you can create one now for free. Create an account or log in at https://cloud.darcy.ai .
Once you are in your Darcy Cloud account, add your device as a node in your current project . Use the “plus button” in the bottom left to add a node. Follow the instructions in the pop-up window to add your device as a node.
Create your application YAML
Here is a sample YAML file to work with.
kind: Application apiVersion: iofog.org/v3 metadata: name: your-application-name spec: microservices: - name: your-microservice-name agent: name: your-darcy-cloud-node-name images: arm: "YOUR_ORGANIZATION/YOUR_APP:tag.goes.here" x86: "YOUR_ORGANIZATION/YOUR_APP:tag.goes.here" container: rootHostAccess: true ports: - external: 5005 internal: 80 proxy: true scheme: http volumes: - containerDestination: /dev hostDestination: /dev type: bind accessMode: rw
You can find this sample YAMl file in the
Your application deployment YAML file contains the information that the Darcy Cloud uses to load and
run your Darcy AI application on any device. Replace the placeholder fields with your own
information and save the file with whatever file name you like, such as
For the agent name, which is shown above as
your-darcy-cloud-node-name you should use the actual
node name from your Darcy Cloud account. This is the name that shows for your device which you added
in the steps above.
Deploy your Darcy AI application
Now that you have all of the pieces, it’s easy to deploy your application to your device or any other device. In the Darcy Cloud, click on the “plus button” in the bottom left and choose “app”.
In the pop-up window, choose the “upload your app” option and you will see a drag-and-drop window on the right-hand side. You can drag and drop your YAML file into that window or you can click the " browse and upload" option and then select your YAML file.
The Darcy Cloud will tell you if you have any issues with your YAML file or your app deployment. It will also tell you if your Darcy AI application was deployed successfully. You can then check the status of your application using the Darcy Cloud.
Use your Darcy AI application
When your Darcy AI application has successfully been deployed to your devices, you will see the
running in your Darcy Cloud UI. At this time, your Darcy AI application is fully running on
those devices. If your application has a live video feed, such as the demo application you built in
at port 3456 then you should be able to view the live feed using the
IP address of the device followed by
You have accomplished a great amount at this point. Congratulations! You have developed a Darcy AI application and tested it with your IDE and local development environment. You have packaged your application for a variety of target devices. And you have made a deployment YAML file and used the Darcy Cloud to deploy and manage your Darcy AI application.
Now that you have all of these foundation Darcy AI developer skills, you are ready to build full solutions. Follow the guide to Extend Darcy to build an app for your use case.