# How to create a FLECS app

For information on how to publish your app, see [How to release a FLECS app](/product-docs/engineering/app-publishing-guide/how-to-release-a-flecs-app.md).

## 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](https://github.com/FLECS-Technologies/app-sdk).

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](https://docs.docker.com/engine/reference/builder/)).
* `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>.

{% hint style="warning" %}
Please leave the file .github/workflows/app\_release.yml as is. It is needed for the app release process.
{% endhint %}

### Start even faster with App Templates

If you're looking to accelerate your app development, we also provide **open-source App Templates** for Python and Rust. These templates come with pre-configured Dockerfiles, CI/CD pipelines, and built-in testing, allowing you to get a working app up and running within hours.

You can use them as a starting point for building apps that run on FLECS, whether for edge devices, industrial PCs, or cloud environments.

🔗 [Explore the App Templates on GitHub](https://github.com/FLECS-Technologies?q=dev-template-\&type=all\&language=\&sort=)

### 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:

```docker
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](https://docs.docker.com/engine/reference/builder/).

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](https://github.com/FLECS-Technologies/apps-tech.flecs.ample/blob/main/docker/Dockerfile).

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.

{% hint style="warning" %}
For each `Dockerfile.<variant>` file there needs to be a corresponding `Docker.platforms.<variant>` file for this to work. See [#variants](#variants "mention") for Details.
{% endhint %}

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

{% @github-files/github-code-block url="<https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Dockerfile>" %}

### 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`.

{% hint style="warning" %}
For each `Docker.platforms.<variant>` file there needs to be a corresponding `Dockerfile.<variant>` file for this to work. See [#variants](#variants "mention") for Details.
{% endhint %}

A [Docker.platforms template](https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Docker.platforms) is provided as well, which is used by the example-app ample as is.

{% @github-files/github-code-block url="<https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Docker.platforms>" %}

### manifest.json

The file `manifest.json` contains all the metadata needed for an app. A [template file](https://github.com/FLECS-Technologies/app-sdk/blob/main/templates/docker/Docker.platforms) and [JSON schema](https://github.com/FLECS-Technologies/app-sdk/blob/main/manifest.schema.json) are available as well. The most important parameters will be explained in the following:

<table data-full-width="false"><thead><tr><th width="171">Parameter</th><th width="286">Explanation</th><th>Examples</th></tr></thead><tbody><tr><td>_schemaVersion</td><td>The version of the manifest.json schema<br><strong>Should be left alone</strong></td><td><code>"_schemaVersion": "3.0.0"</code></td></tr><tr><td>app</td><td>The name of the app in reverse domain name notation</td><td><code>"app": "tech.flecs.ample"</code></td></tr><tr><td>version</td><td>The version of the app, gets filled automatically<br><strong>Should be left alone</strong></td><td><code>"version": "##VERSION##"</code></td></tr><tr><td>revision</td><td>The revision of the app, gets filled automatically<br><strong>Should be left alone</strong></td><td><code>"revision": "##FLECS_VERSION##"</code></td></tr><tr><td>image</td><td>The URL where the app image will be uploaded. This is filled automatically.<br><strong>Should be left alone</strong></td><td><code>"image": "flecs.azurecr.io/tech.flecs.ample"</code></td></tr><tr><td>multiInstance</td><td>Defines if it should be possible to run multiple instances of the app one the same system at once</td><td><code>"multiInstance": true</code></td></tr><tr><td>editors</td><td>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.</td><td><p></p><pre class="language-json"><code class="lang-json">"editors": [
{
  "name": "UI",
  "port": 8080,
  "supportsReverseProxy": true
}]
</code></pre></td></tr><tr><td>args</td><td>A list of arguments that will be passed to docker while creating the container of the app.</td><td><code>"args": [ "--launch-arg-1", "--launch-arg-2=8000" ]</code></td></tr><tr><td>capabilities</td><td>The set of capabilities your application needs. See the <a href="https://docs.docker.com/engine/security/#linux-kernel-capabilities">Docker documentation</a> for details.<br>See <a href="https://man7.org/linux/man-pages/man7/capabilities.7.html">here</a> for a list of all capabilities. Currently only <code>NET_ADMIN</code>, <code>SYS_NICE</code>, <code>NET_RAW</code> and <code>IPC_LOCK</code> from this list are allowed. Additionally <code>DOCKER</code> is supported to allow the app to control docker in the host environment.</td><td><code>"capabilities": [ "NET_ADMIN" ]</code></td></tr><tr><td>conffiles</td><td>Describes the config files that are used by the app and should be mounted on the host system. Syntax: <code>&#x3C;filename>:&#x3C;filepath-in-container>:&#x3C;option></code><br>Possible options are <code>ro</code> for read only and <code>rw</code>  for read write. Default is <code>rw</code>.</td><td><p></p><pre class="language-json"><code class="lang-json">[
  "default.conf:/etc/my-app/default.conf",
  "default.conf:/etc/my-app/default.conf:rw",
<strong>  "default.conf:/etc/my-app/default.conf:ro"
</strong>]
</code></pre></td></tr><tr><td>devices</td><td>Defines which devices are mapped from the host to the container of the app.</td><td><code>"devices": [ "/dev/net/tun" ]</code></td></tr><tr><td>env</td><td>Defines environment variables and their value for the apps environment.</td><td><code>"env": [ "MY_ENV=value" ]</code></td></tr><tr><td>ports</td><td>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.</td><td><code>"ports": [ "7447:7447" ]</code></td></tr><tr><td>volumes</td><td>Defines mapping of volumes on the host to the container of the app.</td><td><code>"volumes": [ "my-app-etc:/etc/my-app" ]</code></td></tr><tr><td>labels</td><td>Defines labels of the app. They  are passed to the docker container on creation. For details see <a href="https://docs.docker.com/engine/manage-resources/labels/">https://docs.docker.com/engine/manage-resources/labels/</a></td><td><pre class="language-json"><code class="lang-json"><strong>"labels": [
</strong><strong>  "example-label1",
</strong><strong>  "example-label2=with-value",
</strong><strong>  "example-labe-3=with whitespace"
</strong><strong>]
</strong></code></pre></td></tr></tbody></table>

### build-app.sh

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

{% hint style="info" %}
To run this script, the user must belong to the `docker` group or have root privileges, as it uses privileged docker commands.
{% endhint %}

The simplest usage is

```shell-session
./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

```shell-session
./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](https://github.com/FLECS-Technologies/app-sdk/blob/main/build-app.sh).

### 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](#docker.platforms "mention") and [#dockerfile](#dockerfile "mention") for Details. If you wish to build this variant with [#build-app.sh](#build-app.sh "mention") you need to provide the additional parameter `--variant <variant>`. An example can be seen in the [tech.flecs.ample](https://github.com/FLECS-Technologies/apps-tech.flecs.ample) project which includes one variant with debug symbols.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flecs.tech/product-docs/engineering/app-publishing-guide/how-to-create-a-flecs-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.