Applications

• 1: Develop an application
• 2: Deploy an application
• 3: Configure applications via configuration maps
• 4: Deploy with private container registries
• 5: Deploy to multiple devices
• 6: Access your deployed application
• 7: Monitor and control applications

1 - Develop an application

This page describes how to develop applications for the SPEKTRA Edge platform.

SPEKTRA Edge utilizes the Docker containers to package and deploy applications for your devices. We follow the standard docker build process for creating applications so that you can benefit from the knowledge and experience you may already have through the prior application development process. Once the image is built, you publish it to one of the container registries to make devices to retrieve and run it on the device.

What you need

To build and publish the application image to the registry, you need:

1. Docker Engine on your local machine
2. access to the container registry

Follow the Docker installation guide to install Docker Engine on your machine. For the container registry access, please consult your container registry documentation, e.g. Docker Hub quickstart guide.

Dockerfile

SPEKTRA Edge application development starts with a Dockerfile.

Here is a quote from the official Docker documentation:

Docker builds images by reading the instructions from a Dockerfile. A Dockerfile is a text file containing instructions for building your source code. The Dockerfile instruction syntax is defined by the specification reference in the Dockerfile reference.

Those are the typical instructions used in Dockerfile:

• FROM <image>

  initializes a new build stage and sets the base image for subsequent instructions.

• RUN <command>

  executes any commands to create a new layer on top of the current image.

• WORKDIR <directory>

  sets the working directory for any RUN, CMD, ENTRYPOINT, COPY, and ADD instructions that follow it in the Dockerfile.

• COPY <src> <dest>

  copies new files or directories from <src> and adds them to the filesystem of the image at the path <dest>.

• CMD <command>

  sets the command to be executed when running a container from an image.

Python Flask application example

Let’s take a look at the example Dockerfile, which builds the simple Python Flask application:

# syntax=docker/dockerfile:1
FROM ubuntu:22.04

# Prepare the python environment on the image.
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install flask==3.0.*

# Copy the Flask app to the image.
COPY hello.py /

# Run the Flask app.
ENV FLASK_APP=hello
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]

with the following hello.py file:

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
  return "Hello World!"

Place those two files on your current directory.

$ tree .
.
├── Dockerfile
└── hello.py

1 directory, 2 files

then, run the following command to build your application image.

docker build --tag test:latest .

You can give any tag name here, for example awesome:v1.0.0, but pick the one you can remember, as you will reference it when you push it to the container registry.

Now, your application image is ready. Let’s publish it to the container registry next.

Push to registry

Repositories let you share container images to be downloaded by the devices.

In this section, we’ll use the Docker Hub as the container registry, as it’s free and publicly accessible. Please consult your container registry documentation in case you use other one.

You can create a free account on Docker Hub. Please follow the Docker Hub quickstart guide to create one if you haven’t created.

Here is the simple step to publish your application to the Docker Hub:

1. Login to the Docker Hub:

   docker login
   

2. Re-tag the image you build in the previous step to point to the Docker Hub repository you own:

   docker tag test:latest <hub-user>/<repo-name>:<tag>
   

3. Push the image to the registry:

   docker push <hub-user>/<repo-name>:<tag>
   

Please consult the official Docker documentation if you get error with those commands.

Next steps

Once you develop your application and publish it to the registry, it’s time to deploy it on your device. Please move on to the deployment document next.

2 - Deploy an application

Once you have developed and published your application image to a container registry, it is time to deploy it to your device.

SPEKTRA Edge provides the Docker compose environment on your device so that you can declare your application in the standard Docker compose file format to run it on your device.

Let’s create a compose.yaml file for the application we developed in the previous section and deploy it on your device through the SPEKTRA Edge dashboard.

What you need

To deploy your application on your device, you need:

• the Docker Compose environment on your local machine, for local verification
• access to the SPEKTRA Edge dashboard
• a device provisioned through the SPEKTRA Edge dashboard

And also, the cuttle CLI command is necessary to complete this tutorial, which is used to access the application from the local machine for the verification purpose. However, it is not required for deploying applications on SPEKTRA Edge.

Local verification

Let’s create and verify compose.yaml file on your local machine.

compose.yaml

Here is the compose.yaml file to deploy the application we developed in the previous section.

services:
  app:
    image: spektraedge/awesome:latest
    ports:
    - 8000:8000

Let’s go over the file line-by-line.

• services

  This is the top level element of the compose file to abstract the definition of a computing resource within an application which can be scaled or replaced independently from other components.

  You can take a look at the official documentation for more detail.

• app

  This is the name of the service, which represents the service definition. We name it app here but it’s free to use different names.

• image

  image specifies the image to start the container from. image must follow the Open Container Specification, as

  [<registry>/][<project>/]<image>[:<tag>|@<digest>].

• ports

  The ports is used to define the port mappings between the host machine and the containers. This is crucial for allowing external access to service running inside containers.

  This example exposes the container application’s port 8000 to be accessible through the local machine’s port 8000.

  Please take a look at the official document for the ports attribute definition.

SPEKTRA Edge compose conventions

Your compose file runs on the device through a managed pod driver, which behaves slightly differently from a plain docker compose up in your project folder. Keep these two conventions in mind when authoring compose.yaml.

• Use absolute host paths for bind mounts. The driver stores each pod’s compose file in its own state directory on the device and runs docker compose from there, so a relative bind-mount source is resolved against that internal directory — not a project folder you control. Docker then auto-creates the missing path there and the agent logs a repeating failed to read compose file ...: is a directory error. Use an absolute host path on a persistent filesystem instead. On SPEKTRA Edge OS that is /isodevice/data, which survives power cycles and OS upgrades (on a .deb install, use an absolute path on your host’s own persistent storage). Better still, mount configuration through a configuration map and host volume:

  services:
  app:
    volumes:
      # Avoid — relative source resolves inside the driver's state directory:
      # - ./config:/etc/app/config
      #
      # Prefer — an absolute path on the persistent data partition:
      - /isodevice/data/myapp/config:/etc/app/config

• Do not set container_name. The driver tracks and reconciles containers using its own naming convention (derived from the pod name). A custom container_name no longer matches that convention, so the agent treats the container as potentially unmanaged and falls back to re-scanning manifests to re-associate it. Omit container_name and let the driver assign names.

docker compose up

With the compose.yaml file ready on your local machine, run docker compose up command in the directory where the file locates:

$ tree .
.
└── compose.yaml

1 directory, 1 file

$ docker compose up
[+] Running 2/0
 ✔ Network sample_default  Created                                        0.0s
 ✔ Container sample-app-1  Created                                        0.0s
Attaching to app-1
app-1  |  * Serving Flask app 'hello'
app-1  |  * Debug mode: off
app-1  | WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
app-1  |  * Running on all addresses (0.0.0.0)
app-1  |  * Running on http://127.0.0.1:8000
app-1  |  * Running on http://172.20.0.2:8000
app-1  | Press CTRL+C to quit

Here you can see the application running and listening on the port 8000 on your local machine.

Point your browser to http://localhost:8000 to verify your application.

Deploy to your device

With the compose.yaml ready, let’s deploy your application on your device through the SPEKTRA Edge dashboard.

Go to the project overview page and click Deploy pod.

Select Deploy on a single device option and provide the following information.

1. Application name
2. Application description
3. Docker compose, compose.yaml file for your reference
4. Target device to deploy

Then, click Deploy to deploy your application.

Congratulations!

You now deployed your application on your device through the SPEKTRA Edge dashboard.

Verify your application

You can verify your application’s health from the SPEKTRA Edge dashboard.

The application page provides the following statistics:

• Application’s overall status
• Each container’s status
• Each container’s CPU utilization
• Each container’s memory utilization
• Application’s logs

You can also restart the application by clicking the Restart option of the drop down menu right next to the application’s name:

Or you can edit the applications, e.g. compose.yaml, by clicking the Edit option of the drop down menu right next to the application’s name:

Now, let’s access your application from your local machine by utilizing the SPEKTRA Edge port-forwarding feature. Simply copy the cuttle command provided by the dashboard located under the Docker compose section:

Open the terminal on your local machine. Paste the command you just copied onto your terminal and run it to enable the port-forwarding to access your application from the local machine.

Here is the example port-forward command for your reference. It enables your application, which is listening on device’s port 8000, reachable through your local machine’s port 8000.

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/raspberry-pi-5 \
  8000 tcp://127.0.0.1:8000

With the above port-forwarding command running, point your browser to http://localhost:8000 to access your application from your local machine.

You will get the same result you got during the local verification.

Next steps

With the application running on your device, learn how to supply it with configuration, so the same image can behave differently in different places.

3 - Configure applications via configuration maps

Let’s learn how to configure applications via configuration maps on SPEKTRA Edge.

A configuration map allows you to decouple environment-specific configuration from your application images, so that your applications are easily portable.

You can map the application configuration to the particular containers under the application with the following steps:

1. Create a configuration map
2. Create an application with docker compose volumes service attribute to describe the configuration to be mounted on the container through the following two levels of indirection:
   1. Configuration map volume to map the configuration map to the application
   2. Host volume to mount the configuration to the host environment so that the application can mount the configuration to the particular container.

We’ll use the Nginx application and source the configuration file through the configuration map to demonstrate how to use the configuration map on SPEKTRA Edge.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project

And also, the cuttle CLI command is necessary to complete this tutorial, which is used to access the Nginx application from the local machine for the verification purpose. However, it is not required for deploying applications on SPEKTRA Edge.

Application files

compose.yaml

It’s a simple Nginx application with mapping the port 8000 with the configuration directory mounted through the volumes attributes.

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000
    volumes:
    - /isodevice/data/nginx/conf.d:/etc/nginx/conf.d

nginx.conf

Here is the Nginx configuration file, which will be mapped to the application through the SPEKTRA Edge configuration map.

It’s a simple configuration file, which make it listen on the port 8000, instead of port 80. Since we override the default configuration, we also sets the content root to the default Nginx content directory with root directive.

server {
  listen 8000;
  root /usr/share/nginx/html;
}

Deploy the application

Let’s deploy the application with the configuration map on SPEKTRA Edge.

Here are the steps to follow:

1. Create a configuration map
2. Create the application with two new resources:
   • the configuration map volume to map the configuration map created above to the application
   • the host volume to mount the configuration to the host environment for the load balancer container to mount the configuration file to.

Let’s do it.

Create a configuration map

Let’s create a configuration map to store the Nginx configuration file on SPEKTRA Edge.

First, select the Config maps option of the Applications pull-down menu.

Then, create a configuration map by pasting the nginx.conf file content in the data key value field with the default.conf as the data key name.

Make sure you set:

• nginx-conf as the configuration map name
• default.conf as the configuration data key name

Those names are important because it’s referenced by the other object in the later steps.

Create the application

With the Nginx configuration map ready, let’s deploy the application.

Here is what we’ll do:

1. Paste the docker compose file content to the Docker Compose field
2. Create a volume config map for the Nginx configuration file mapping
3. Create a host volume to mount the above configuration map to the device

We’ll go over those points step-by-step below but first, let’s have a Deploy pod page ready by clicking the Deploy pod button on the Project overview page.

Docker compose file

Let’s paste the docker compose file to the Docker Compose field of the Deploy pod page.

Volume configuration map

The next is the volume configuration map, which maps the Nginx configuration file we created before to the application as a volume.

Here is the key points to highlight:

• Select the correct configuration map
  • projects/your-project/regions/us-west2/configMaps/nginx-conf for this example
• Specify the correct select key of the configuration map item
  • default.conf in this example, as we specified as the key value name for the Nginx configuration file when we created the configuration map.
• Use default.conf for the path name of the select key
  • This is the file name which will be shown in the container. Nginx expects this file name as the default Nginx configuration file.

Host volume

This is the last item to configure on the Deploy pod page.

It mounts the volume configuration map we create above to the host environment of the device. This file will be mounted to the Nginx load-balancer container through the docker compose file we explained before.

Again, there are a couple of things to make it right.

• the volume name should match the name of the volume configuration map we created above
  • nginx-conf in this example
• the Volume mount path should be matched to the one specified in the docker compose
  • /isodevice/data/nginx/conf.d in this example

Click to deploy

With all those configuration set, click the Deploy button on the Deploy pod page to deploy the application on your device.

With a minute or so, you should be able to see the application running on your device, as below.

Verify the application

Let’s verify the application by accessing it through the port forwarding.

Go to the application overview page by clicking the name of the app, Three tier web app in this example, on the Project overview page.

From there, copy the port forward command by clicking the Copy port forward as Cuttle command button on the application overview page.

Run the command on your local terminal window to make your application accessible from your browser.

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/pp-quick-202410-dmphwxuzhh8nyw \
  8000 tcp://127.0.0.1:8000

Please note that the device name above will be different for your case.

Point your browser to http://localhost:8000 and you should be able to see the page below.

Next steps

Congratulations on configuring the Nginx application with the configuration map on SPEKTRA Edge.

If your image lives somewhere that needs credentials, continue with private registry.

4 - Deploy with private container registries

Let’s learn how to deploy applications from the private container registries.

SPEKTRA Edge supports private container registries, such as Amazon Elastic Container Registry, Azure Container Registry, or Google Artifact Registry, as the application container registries.

In this document, we’ll learn how to configure the application on SPEKTRA Edge to run the container image hosted on the Azure container registry, a private container registry offered by Microsoft Azure.

What you need

Please have those ready before proceeding:

• Docker Engine and Azure CLI on your local machine
• access to the SPEKTRA Edge dashboard
• a device provisioned under your project on SPEKTRA Edge
• access to Azure portal and Azure Container Registry

Push to private registries

We’ll first publish the application image to the Azure container registry.

We’ll use the same application we developed in the develop section. Here is the Dockerfile and hello.py files for your reference.

# syntax=docker/dockerfile:1
FROM ubuntu:22.04

# Prepare the python environment on the image.
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip install flask==3.0.*

# Copy the Flask app to the image.
COPY hello.py /

# Run the Flask app.
ENV FLASK_APP=hello
EXPOSE 8000
CMD ["flask", "run", "--host", "0.0.0.0", "--port", "8000"]

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
  return "Hello World!"

Copy those two files and place those under the directory like below.

$ tree .
.
├── Dockerfile
└── hello.py

1 directory, 2 files

Under that directory, run the following docker build command to create the application image tagged with the Azure container registry and repository name for the publication in the following step.

docker build --tag spektraedge.azurecr.io/awesome .

Publish the image to the Azure container registry with docker push command.

docker push spektraedge.azurecr.io/awesome:latest

Once it’s pushed, go to the Azure portal and double check if the application image correctly published on Azure container registry.

Now, you’re ready to configure the application to pull the image from the Azure container registry. But before that, let’s talk about the image secrets next.

Image secrets

The image secrets is a special secret resource maintained by the SPEKTRA Edge platform. It’s meant to be used for storing the credentials to access the private container registries. Hence, we’ll configure the image secrets next before configuring the applications.

Let’s create one here.

Go to the Secrets page by selecting the Secrets from the Applications pull-down option from the left navigation menu.

1. Secret display name
2. Secret data key name
3. Secret data key value

Secret display name

This is a case-insensitive alpha-numeric secret name referenced later by the application configuration. Give it a descriptive name for the better secret management.

Secret data key name

This field should be .dockerconfigjson. This follows the Kubernetes convention.

Secret data key value

This field contains the base64 encoded private registry credential with the following JSON format.

{
  "auths": {
    "$REGISTRY_URL": {
      "username":"$USERNAME",
      "password":"$PASSWORD"
    }
  }
}

In case of the Azure container registry, you can generate the above JSON string by the following shell script with Azure CLI

echo \
  {\"auths\":\
    {\"$(az acr show --name $REGISTRY_NAME --query loginServer --output tsv)\":\
      {\"username\":\"$(az acr credential show --name $REGISTRY_NAME --query username --output tsv)\",\
       \"password\":\"$(az acr credential show --name $REGISTRY_NAME --query passwords[0].value --output tsv)\"\
      }\
    }\
  }

where you set $REGISTRY_NAME environment variable to your Azure container registry name, e.g. spektraedge in this example.

Convert to base64

Once you have those three values ready, you paste those in the respective fields and click Convert to Base64 button of the Add secret page.

Create the image secret

Click Create to create the image secret for the Azure container registry.

Deploy the application

For the application deployment, we’ll follow the standard application deployment explained in the previous section except one field, the image secrets.

On the Deploy pod page, select the image secret you created in the previous step and just click Deploy as usual.

Next steps

Congratulations on mastering the deployment with the private container registry on SPEKTRA Edge!

So far you have deployed to one device at a time. Next, learn how to deploy to multiple devices at once.

5 - Deploy to multiple devices

Let’s learn how to deploy the application on multiple devices on SPEKTRA Edge.

There are two steps for this process to work:

1. Set a device label to the target devices
2. Create a pod template with selecting the label above as the target device label

With that, let’s get to work.

What you need

To deploy applications on multiple devices on SPEKTRA Edge, you need:

• access to the SPEKTRA Edge dashboard
• devices provisioned under your project on SPEKTRA Edge

Set device labels

Let’s set the device label on multiple devices to group those together as the deployment target.

Open the Update device details page of the Device overview page by selecting the Edit details option of the Device menu.

Set the device label, task:multi-devices in this example, on the Update device detail page as a label to group multiple devices together.

Please do the same for other devices as well before moving on to the deployment step next.

Deploy with pod templates

Once you set the device labels on your target devices, now is the time to deploy applications on all those devices in one-shot with a pod template.

The pod template is a template to apply application deployment against multiple devices, similar to the template field of the deployments manifest in Kubernetes.

Let’s create one to see it in action. We’ll use the same application we used for the single device deployment to demonstrate how easy and similar deploying applications on multiple devices.

Go to the Project overview page and click Deploy pod button.

Use the Pod template option in Deploy pod page this time and select the target devices by providing the device label, task:multi-devices in this example, in the Target device labels to deploy field, in addition to the other application information similar to one for the single device deployment.

Click Deploy to deploy it on multiple devices.

Once it’s done, you should be able to see applications all running on the target devices, five devices in this example, from the Project overview page.

Next steps

Congratulations on successfully deploying the application on multiple devices in a single-shot on SPEKTRA Edge.

Next, learn how to access a running application from your own machine to check it is behaving.

6 - Access your deployed application

Let’s learn the ways to reach an application running on your device with SPEKTRA Edge.

Once you deploy an application, its containers run on the device and publish ports according to your Docker compose file. How you reach those ports depends on where you are relative to the device. This page covers the three common cases:

1. From your workstation, anywhere — through the platform’s secure port forwarding (no inbound ports open on the device).
2. From the device’s local network — directly to a published port.
3. From another container — service-to-service inside the same application.

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000

From your workstation (port forwarding)

This is the recommended way to reach an application on a remote device. It works from anywhere, over the device’s existing outbound connection to the platform, so no inbound ports need to be open on the device or its network.

You need the cuttle CLI installed for this method.

1. Open the application’s Application overview page in the dashboard (see Monitor & control).
2. Click Copy port forward as Cuttle command to copy a ready-made command.
3. Run it in your local terminal. For example:

cuttle devices forward-port \
  projects/your-project/regions/us-west2/devices/your-device \
  8000 tcp://127.0.0.1:8000

This forwards the device’s port 8000 to 127.0.0.1:8000 on your machine. Point your browser at http://localhost:8000 and you’ll reach the application as if it were running locally.

The first argument is the full device name (it includes the project and region); the dashboard fills this in for you when you copy the command.

From the device’s local network

If your client (a browser, another machine, a PLC, etc.) is on the same local network as the device, you can reach a published port directly using the device’s IP address:

http://<device-ip>:<published-port>

For the Nginx example above, that would be http://<device-ip>:8000.

This is the natural choice when the application is meant to serve other equipment on-site — for example, a local dashboard, an API consumed by nearby machines, or a gateway service.

A few things to keep in mind:

• The port must be published in the compose file (the ports entry). A container port that isn’t published is only reachable from inside the device.
• By default a published port is reachable on all of the device’s network interfaces. If you only want it on a specific interface, bind it explicitly in the compose file, for example 127.0.0.1:8000:8000 to keep it on the device itself.
• Make sure the chosen host port doesn’t collide with another application or a system service on the device.

From another container

Containers within the same application can talk to each other over the application’s internal network using their service name as the hostname — they don’t need to publish ports for this. For example, an app service can reach a redis service at redis:6379.

Only publish a port (with ports) when something outside the application needs to reach the container. Internal service-to-service traffic should stay on the internal network.

Persisting data behind your application

If your application stores data (uploads, a database, configuration), mount it under the device’s persistent data area so it survives restarts and power cycles:

services:
  app:
    image: nginx:alpine
    ports:
    - 8000:8000
    volumes:
    - /isodevice/data/nginx/conf.d:/etc/nginx/conf.d

See Configuration for a full walk-through of mounting configuration and host volumes.

Which method should I use?

Next steps

Learn how to monitor and control your application — view its status, metrics, and logs — from the SPEKTRA Edge dashboard.

7 - Monitor and control applications

Let’s learn how to monitor and control applications on SPEKTRA Edge.

What you need

To go through this page, you need the following.

• access to the SPEKTRA Edge dashboard
• an active project
• a device provisioned under the project
• an application running on the device
• the cuttle CLI installed locally, to use port forwarding

With these, let’s dive in managing applications on SPEKTRA Edge.

Application overview

Application overview page is the main dashboard to manage applications on SPEKTRA Edge.

To get there from the Project overview page, click the Manage pods button located in the Pods section of the Project overview page.

Click the name of the application you want to manage, counter in this example, to get to the Application overview page of the application.

Here on the Application overview page, you can do the majority of the tasks to manage applications, such as:

• observing the application’s status
• checking the application’s Docker compose file content
• monitoring the application’s resource usages, such as CPU and memory
• examining the application’s logs
• controlling your application

It also offers the cuttle port forward command, which you can copy and run on your local machine to access your application through the SPEKTRA Edge port forwarding capability.

Application statuses

Here is the list of application statuses monitored on SPEKTRA Edge.

Container states

Here is the list of Container’s state, which is the composition of the application status explained above. The Containers section of the Application overview page shows the container states.

Application metrics

You can monitor the container’s resource usage on the dashboard.

Go to the Containers usage section of the Application overview page and select the type of resource you want to monitor. Click the right side of the time range section to specify the duration of the time-series to be shown on the graph.

Application logs

You can retrieve each container’s logs on the dashboard.

Specify the name of the container you want to show the logs by clicking the pull down menu of the Logs section on the Application overview page.

Click Start to retrieve the live logs of the container.

You can also download the logs by clicking the Download icon on the Logs menu bar.

Control applications

You can control applications from the dashboard.

Here is the list of operations you can perform:

• delete
• restart

Click the vertical three-dots right next to the application’s name in the Application overview page to show the pull-down menu and select the operation you want to perform.

Next steps

That completes the application lifecycle: you can build an image, deploy it, configure it, reach it, and watch it run.

Next, turn to the hardware underneath. Devices covers setting up and operating the machines your applications run on.