ExApp development

ExApp development process is similar to the development of the regular Nextcloud PHP app, and should follow the same guidelines in terms of security, design and coding style (ref) based on your programming language standards.

Despite the fact, that ExApp can be developed in any language, it’s still recommended to have the understanding of the Nextcloud PHP request life cycle and other basic concepts, as they are usually similar to the ExApp backend to which Nextcloud communicates.

You can think about ExApp like a microservice (Docker container) that runs separately from Nextcloud on the Deploy daemon, which can be remote or local. The communication between Nextcloud and ExApp is done via network secured with AppAPI authentication (Authentication).

Lets go through the ExApp development steps briefly.

0. Setting up the development environment

First of all, you need to have a Nextcloud dev setup, refer to Development environment for more details.

1. Starting from template

Next step, is to setup the ExApp skeleton. There are several ExApp examples available so you can have a look at them and start from. The ExApp template and examples:

They contain the basic structure of the ExApp, including:

  • Dockerfile

  • ExApp backend

  • ExApp frontend

  • Manual translations tools setup and example script to convert translation files to Nextcloud l10n format and for your programming language

  • Some necessary GitHub workflows (e.g. Docker image build workflows)

More details are available in the ExApp overview section.

3. Development

The development process basically contains from the following steps:

  • Implement the ExApp <-> Nextcloud lifecycle methods:

    1. /heartbeat: ExApp heartbeat method.

    2. /init: ExApp initialization method.

    3. /enabled: ExApp enable/disable method.

  • Implement the ExApp backend API and logic.

  • Implement the ExApp frontend (Nextcloud Vue.js app) [optional].

4. Packaging

The ExApp packaging can be done manually, or via GitHub actions. It is recommended to use GitHub actions for packaging, as it will automate the process of building the Docker image and pushing it to the Docker registry. The GitHub action workflow for building Docker images can be found in the 3rdparty service example.

4.1 Hardware acceleration

If your ExApp work with GPUs, you should consider building different Docker images for each compute device. Currently, there are 3 main compute devices to target with custom Docker images:

  • CPU (default, no specific tag)

  • GPU: CUDA (NVIDIA) (<image_name>:<version>-cuda)

  • GPU: ROCm (AMD) (<image_name>:<version>-rocm)

Note

If the Deploy daemon configured with the GPU compute device, AppAPI will try to pull the Docker image with the GPU support first (<image_name>:<version>-<cuda|rocm>, ref PR). If the image is not found, AppAPI will try to pull the base (CPU) image (<image_name>:<version>).

Dockerfile

The Dockerfile is required to build the Docker image for the ExApp. The guideline for writing the Dockerfile can be found in the Dockerfile best practices.

Short recommendations:

  1. Keep the Dockerfile as small as possible.

  2. Use minimal base images to keep the image size small.

  3. Place rarely changing instructions at the top of the Dockerfile to take advantage of Docker’s caching mechanism.

Logging

The logs in Docker container are shown from the standard output and error streams. To be able admin to see the important logs from ExApp container, you should consider redirecting the logs to the standard output and standard error streams. More info in official docs for logging.

5. AppStore publishing

Once the ExApp is ready, and the Docker image is available in the Docker registry, you can follow the AppStore publishing process. It’s the same as for the regular Nextcloud app, but with the requirement of the ExApp specific fields in the appinfo/info.xml file.

6. Testing

It is important to ensure that your ExApp works as expected. We recommend to have different types of dev setup configuration to test all of them. While the main development is done locally via manual_install, you must also ensure that the ExApp works correctly in Docker container with http and https Docker Socket proxy.