🪛How to create a FLECS app

For information on how to publish your app, see How to release a FLECS app.

How to create an app

We provide a repository on GitHub where you can create your app. To support the development process, we provide file templates and scripts in this repository, which are also available on GitHub.

While you can change the content of the repository to your needs, three files in the repository need to be edited by you and kept in place:

• docker/Dockerfile describing how the Docker container of the app is built (Dockerfile reference).

• docker/Docker.platforms defining for which platforms the app can be built.

• manifest.json providing the necessary meta information for the app.

The following sections will explain how to use them and provide more detail on their contents. We provide an example app you can take a look at: https://github.com/FLECS-Technologies/apps-tech.flecs.ample.

Please leave the file .github/workflows/app_release.yml as is. It is needed for the app release process.

Dockerfile

The Dockerfile provides instructions for obtaining a working build of the app, ranging from a simple download to a complex multi-stage build process. If a Docker image is already available for the app, it can be copied as demonstrated below:

ARG ARCH
ARG VERSION
ARG VARIANT

FROM flecspublic.azurecr.io/apps-tech.flecs.ample:${VERSION}

ARG ARCH
ARG VERSION
ARG VARIANT

RUN [ ! -z "${ARCH}" ]
RUN [ ! -z "${VERSION}" ]

For information on how to write a Dockerfile, refer to the Dockerfile reference.

In our example-app ample, the Dockerfile copies a flecs-build image that provides the build environment, then copies the source code into the container and finally builds the app using cmake. The file can be viewed here.

To create different variants of an app, you can provide additional Dockerfiles. The file name must follow the pattern Dockerfile.<variant>. For example Dockerfile.debug, Dockerfile.hardened or Dockerfile.premium.

For each Dockerfile.<variant> file there needs to be a corresponding Docker.platforms.<variant> file for this to work. See Variants for Details.

To jumpstart the process, a basic template Dockerfile is provided. The Dockerfile receives the variables ARCH, VERSION, and optionally VARIANT during the build process.

https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Dockerfile

ARG ARCH
ARG VERSION
ARG VARIANT

FROM scratch:${VERSION}

ARG ARCH
ARG VERSION
ARG VARIANT

RUN [ ! -z "${ARCH}" ]
RUN [ ! -z "${VERSION}" ]

Docker.platforms

The Docker.platforms file defines the platforms the app can be built for. The format follows the same syntax that is used by Docker: <operating system>/<architecture> for example linux/amd64. The platforms appear in the first line of the file separated by commas.

Additional Docker.platforms files can be provided to allow the creation of different variants of an app. The file name has to follow the pattern Docker.platforms.<variant>. For example Docker.platforms.debug, Docker.platforms.hardened or Docker.platforms.premium.

For each Docker.platforms.<variant> file there needs to be a corresponding Dockerfile.<variant> file for this to work. See Variants for Details.

A Docker.platforms template is provided as well, which is used by the example-app ample as is.

https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Docker.platforms

linux/amd64,linux/arm/v7,linux/arm64

manifest.json

The file manifest.json contains all the metadata needed for an app. A template file and JSON schema are available as well. The most important parameters will be explained in the following:

Parameter	Explanation	Examples
_schemaVersion	The version of the manifest.json schema Should be left alone	"_schemaVersion": "3.0.0"
app	The name of the app in reverse domain name notation	"app": "tech.flecs.ample"
version	The version of the app, gets filled automatically Should be left alone	"version": "##VERSION##"
revision	The revision of the app, gets filled automatically Should be left alone	"revision": "##FLECS_VERSION##"
image	The URL where the app image will be uploaded. This is filled automatically. Should be left alone	"image": "flecs.azurecr.io/tech.flecs.ample"
multiInstance	Defines if it should be possible to run multiple instances of the app one the same system at once	"multiInstance": true
editors	Defines the ports on which a web interface of the app is reachable. For example to configure the app or view statistics. It is not necessary to forward the ports via the "ports" section. Flecs will handle accessing the editor.	"editors": [ { "name": "UI", "port": 8080, "supportsReverseProxy": true }]
args	A list of arguments that will be passed to docker while creating the container of the app.	"args": [ "--launch-arg-1", "--launch-arg-2=8000" ]
capabilities	The set of capabilities your application needs. See the Docker documentation for details. See here for a list of all capabilities. Currently only NET_ADMIN, SYS_NICE, NET_RAW and IPC_LOCK from this list are allowed. Additionally DOCKER is supported to allow the app to control docker in the host environment.	"capabilities": [ "NET_ADMIN" ]
conffiles	Describes the config files that are used by the app and should be mounted on the host system. Syntax: <filename>:<filepath-in-container>:<option> Possible options are ro for read only and rw for read write. Default is rw.	[ "default.conf:/etc/my-app/default.conf", "default.conf:/etc/my-app/default.conf:rw", "default.conf:/etc/my-app/default.conf:ro" ]
devices	Defines which devices are mapped from the host to the container of the app.	"devices": [ "/dev/net/tun" ]
env	Defines environment variables and their value for the apps environment.	"env": [ "MY_ENV=value" ]
ports	Defines mapping of ports of the host to the container of the app. This is only necessary for ports the app listens to as a server, similar to firewall settings.	"ports": [ "7447:7447" ]
volumes	Defines mapping of volumes on the host to the container of the app.	"volumes": [ "my-app-etc:/etc/my-app" ]
labels	Defines labels of the app. They are passed to the docker container on creation. For details see https://docs.docker.com/engine/manage-resources/labels/	"labels": [ "example-label1", "example-label2=with-value", "example-labe-3=with whitespace" ]

build-app.sh

This script can be used to (test) build your app. It is also used during the release process.

To run this script, the user must belong to the docker group or have root privileges, as it uses privileged docker commands.

The simplest usage is

./build-app.sh --app <reverse domain app name> --version <app version>

which builds all versions of the app for the standard variant. For the example app it could look like

./build-app.sh --app tech.flecs.ample --version  v1.0.0

The parameter --variant followed by the name of the variant can be specified to build a specific variant of the app. For example:

./build-app.sh --app tech.flecs.ample --version  v1.0.0 --variant debug

The script can be found here.

Variants

Different variants of your app can be created. One possible variant could include binaries with debug information for debugging purposes or enhanced security features.

To create a variant you need to provide an additional Dockerfile and Docker.platforms. These files need to follow the naming patterns Docker.platforms.<variant> and Dockerfile<variant>. The variant needs to be all lowercase and match between both files. The Dockerfile needs to specify how this variant is built, while Docker.variants provides the platforms this variant is available for. See Docker.platforms and Dockerfile for Details. If you wish to build this variant with build-app.sh you need to provide the additional parameter --variant <variant>. An example can be seen in the tech.flecs.ample project which includes one variant with debug symbols.