Deployment

Overview

The ExApp deployment process consists of 2 steps:

  1. DaemonConfig registration

  2. ExApp registration

DaemonConfig registration

The first step is to register the DaemonConfig, where your ExApps will be deployed. Before that, you will need to set up HaRP with access to the Docker Engine.

Note

The Docker daemon accepts-deploy-id: docker-install requires HaRP (--harp). For development and manually deployed apps in Docker, there is accepts-deploy-id: manual-install.

This can be done by the occ app_api:daemon:register command:

app_api:daemon:register <name> <display-name> <accepts-deploy-id> <protocol> <host> <nextcloud_url> [--net NET] [--compute_device DEVICE] [--set-default] [--harp] [--harp_frp_address ADDRESS] [--harp_shared_key KEY] [--]

Arguments

  • name - unique name of the daemon (e.g. harp_proxy_host)

  • display-name - name of the daemon (e.g. My Local Docker, will be displayed in the UI)

  • accepts-deploy-id - type of deployment (docker-install or manual-install)

  • protocol - protocol used to connect to the daemon (http or https)

  • host - host and port of HaRP (e.g. appapi-harp:8780), or the ExApp host for manual-install without HaRP

  • nextcloud_url - Nextcloud URL, Daemon config required option (e.g. https://nextcloud.local)

Options

  • --net [network-name] - [required] network name to bind docker container to (default: host)

  • --compute_device DEVICE - [optional] GPU device to expose to the daemon (defaults to cpu, but cuda and rocm are also supported)

  • --set-default - [optional] sets the newly created daemon as the default

  • --harp - [optional] use HaRP for all Docker and ExApp communication, required for docker-install

  • --harp_frp_address ADDRESS - [optional] host:port of the HaRP FRP server

  • --harp_shared_key KEY - [optional] HaRP shared key, must match HP_SHARED_KEY of the HaRP container

Note

Common configurations are tested by the CI in our repository, see workflows on GitHub.

Example

Example of occ app_api:daemon:register command:

sudo -E -u www-data php occ app_api:daemon:register harp_proxy_host "Harp Proxy (Host)" docker-install http localhost:8780 "https://nextcloud.local" --harp --harp_frp_address localhost:8782 --harp_shared_key "some_very_secure_password"

ExApp registration

The second and final step is to deploy and register ExApp in Nextcloud on a previously registered daemon. This can be done by the occ app_api:app:register command:

app_api:app:register [--info-xml INFO-XML] [--json-info JSON-INFO] [--] <appid> <daemon-config-name>

Arguments

  • appid - unique name of the ExApp (e.g. app_python_skeleton, must be the same as in deployed container)

  • daemon-config-name - unique name of the daemon (e.g. harp_proxy_host)

Options

  • --info-xml INFO-XML [optional] - path to info.xml file (url or local absolute path)

  • --json-info JSON-INFO [optional] - ExApp deploy JSON info (json string)

Warning

After successful deployment (pull, create, and start container), there is a heartbeat check with a 10 minute timeout.

Manual install for development

For development purposes, you can install the ExApp manually. There is a manual-install DeployConfig type, which can be used in case of development. To register an ExApp with it, you need to provide the app info as a JSON string or a path to the app’s info.xml file.

For all examples and applications we release, we usually add the manual_install command in it’s Makefile for easier development.

sudo -E -u www-data php occ app_api:app:register nc_py_api manual_install --json-info \
        "{\"id\":\"nc_py_api\",\"name\":\"nc_py_api\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"port\":$APP_PORT}" \

Note

App deployment/startup should be done by the developer when manual-install DeployConfig type is used.

Deploy environment variables

Deploy environment variables are used to configure the ExApp container. The following variables are required and built automatically:

  • AA_VERSION - AppAPI version

  • APP_SECRET - generated shared secret used for AppAPI authentication

  • APP_ID - ExApp app ID

  • APP_DISPLAY_NAME - ExApp display name

  • APP_VERSION - ExApp version

  • APP_HOST - host ExApp is listening on

  • APP_PORT - port ExApp is listening on (randomly selected by AppAPI)

  • APP_PERSISTENT_STORAGE - path to mounted volume for persistent data storage between ExApp updates

  • NEXTCLOUD_URL - Nextcloud URL to connect to

Application installation scheme

  1. AppAPI deploys the application and launches it.

  2. For up to 10 minutes, AppAPI checks the /heartbeat endpoint with a GET request.

  3. AppAPI sends a POST request to the /init endpoint. If the ExApp does not implement the /init endpoint and AppAPI receives a 501 or 404 status code, AppAPI enables the application and goes straight to step 5.

  4. The ExApp sends an integer from 0 to 100 to the OCS endpoint apps/app_api/apps/status indicating the initialization progress. After sending 100, the application is considered initialized.

  5. AppAPI sends a PUT request to the /enabled endpoint.

ExApp info.xml schema

The ExApp info.xml (example) file is used to describe ExApp parameters. It is used to generate the ExApp docker container and register the ExApp in Nextcloud. It has the same structure as other Nextcloud appinfo/info.xml files, but with some additional fields:

...
<external-app>
    <docker-install>
        <registry>ghcr.io</registry>
        <image>nextcloud/talk_bot</image>
        <image-tag>latest</image-tag>
    </docker-install>
</external-app>
...