IXON Edge App Workspace

Welcome to your workspace for developing Edge Apps for the SecureEdge Pro. Edge Apps are Docker Compose-based applications that can be deployed via the IXON Cloud.

You can download this repository as a ZIP file and check it into your preferred versioning system.

Note that you will need to have Docker installed for validating & bundling Edge Apps.

Getting Started

To get started, download this project as a ZIP and extract it to your desired location.

The main file you will be editing is the compose.yaml file. This is the Compose file that defines the services (containers) that are part of the Edge App.

An example compose.yaml file is provided within the project. It contains a simple application that can be accessed at TCP port 1234 (http://localhost:1234).

This workspace includes small scripts for invoking the Edge App CLI, for Linux, macOS & Windows-based systems.

# List supported actions

# Linux or macOS
./edge-app-cli --help

# Windows cmd.exe or PowerShell
.\edge-app-cli.cmd --help

Private container registry credentials

When validating or bundling an Edge App, the Edge App CLI will attempt to retrieve image information from the container registry. If the Edge App CLI is unable to retrieve this information, most commands will return an error that starts with the following:

failed to resolve digest for ...

This error means that either the specified image is not present in the registry (and for example only exists locally), or that the Edge App CLI does not have the permission to pull the image.

In case your Edge App makes use of images that are only available from a private registry, such as a private repository on Docker Hub or an Azure Container Registry, please create the required registry_credentials.json file in your workspace root. You can do so by copying the registry_credentials.example.json file, and updating it to match your registry & the required credentials encoded as base64.

Warning

Make sure the registry_credentials.json file is not checked into version control.

For example, if your registry requires username some-username and password some-token, you can use the following snippet to create a base64-encoded version of these credentials, which can then be used in the registry credentials file:

# Linux/MacOS
echo -n "some-username:some-token" | base64

# Windows cmd.exe or PowerShell
powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes('some-username:some-token'))"

# Example output
c29tZS11c2VybmFtZTpzb21lLXRva2Vu

You can then update the registry_credentials.json file to match the following. The <registry> placeholder is where you specify the address of the registry for which you're configuring the credentials. For instance, if your Edge App uses an image such as registry.my-org.test:2020/private/my-image:v2, the registry.my-org.test:2020-part is the address that should be used.

Important

If you have a private repository on Docker Hub, the address https://index.docker.io/v1/ should be used.

{
  "auths": {
    "<registry>": {
      "auth": "<base64 credentials>"
    }
  }
}

Validating your Edge App

Edge Apps do not support all features normally supported by Docker Compose. To validate your Edge App, run:

# Linux or macOS
./edge-app-cli validate

# Windows cmd.exe or PowerShell
.\edge-app-cli.cmd validate

Uploading your Edge App to IXON Cloud

The following command creates a bundle.zip file and uploads it to IXON Cloud:

# Linux or macOS
./edge-app-cli upload

# Windows cmd.exe or PowerShell
.\edge-app-cli.cmd upload

This command requires two additional files to be created in the root of the project:

• config.json containing the company and Edge App ID. This file can be checked into version control.
  You can get the Edge App ID by navigating to Studio > Edge App, clicking the "Add new Edge App" button and then copying the new Edge App's public ID, or copy the public ID of an existing Edge App.
  You can get the Company ID by opening the account dialog and copying the company ID
• .accesstoken, containing a valid access token, this is the string of 32 characters that can be found in the Authorization header of an API call with the network inspector while browsing the IXON Portal. This file should not be checked into version control.

Example config.json file:

{
  "company": "1111-2222-3333-4444-5555",
  "edgeApp": "a1b2c3d4e5f6"
}

Example .accesstoken file:

hAeD80dCreaZanlUkzh4nPuPpBaop3ku

Updating the Edge App CLI

It may be necessary to update the Edge App CLI in order to make use of new Edge App features. This can be done using the following command:

# Linux or macOS
./edge-app-cli update

# Windows cmd.exe or PowerShell
.\edge-app-cli.cmd update

Support

For more information and support, please check our developer website on developer.ixon.cloud.