mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
113 lines
4.2 KiB
ReStructuredText
113 lines
4.2 KiB
ReStructuredText
.. _app_installation_flow:
|
|
|
|
App Installation Flow
|
|
=====================
|
|
|
|
Image Pulling (Docker)
|
|
----------------------
|
|
|
|
AppAPI **2.5.0+** will always first try to pull a docker image with a ``suffix`` equal to value of *computeDevice*.
|
|
|
|
The following values are available for ``computeDevice``: ``cpu``, ``cuda``, or ``rocm``.
|
|
|
|
The suffix will be added as follows:
|
|
|
|
.. code::
|
|
|
|
return $imageParams['image_src'] . '/' .
|
|
$imageParams['image_name'] . '-' . $daemonConfig['computeDevice']['id'] . ':' . $imageParams['image_tag'];
|
|
|
|
For ``cpu``, AppAPI will first try to get the image from ``ghcr.io/cloud-py-api/skeleton-cpu:latest``.
|
|
In case the image is not found, ``ghcr.io/cloud-py-api/skeleton:latest`` will be pulled.
|
|
|
|
If you as an application developer want to have a custom images for any of these values, you can push the extended images to registry in addition to the base one.
|
|
|
|
Heartbeat
|
|
---------
|
|
|
|
The first thing AppAPI does is deploy the application.
|
|
|
|
In the case of Docker, this means:
|
|
|
|
1. performing an image pull
|
|
2. creating container from the docker image
|
|
3. if the container supports `healthcheck` - AppAPI waits for the `healthy` status
|
|
4. waiting until the “/heartbeat” endpoint becomes available with a ``GET`` request
|
|
|
|
The application, in response to the request "/heartbeat", should return json: ``{"status": "ok"}``.
|
|
|
|
.. note:: The request to ``/heartbeat`` endpoint is made without AppAPI authentication.
|
|
|
|
Init
|
|
----
|
|
|
|
.. note:: Starting from this point, all requests made by AppAPI contains :ref:`auth-headers`.
|
|
|
|
After application is ready, which is determined by previous step,
|
|
AppAPI sends a ``POST`` request to the ``/init`` application endpoint.
|
|
|
|
*If the application does not need to carry out long initialization, it has an option to not implement "/init" endpoint, so
|
|
AppAPI will get 404 or 501 error on it's request, but you can consider that initialization to be done and this section can be skipped.*
|
|
|
|
In case you want to implement "/init" endpoint, your application should:
|
|
|
|
1. In "/init" handler: return a Response with empty JSON data on AppAPI call.
|
|
2. In background job: send an OCS request to ``PUT /ocs/v1.php/apps/app_api/ex-app/status`` with the progress value.
|
|
|
|
.. warning::
|
|
|
|
``PUT /ocs/v1.php/apps/app_api/apps/status/$APP_ID`` is deprecated and will be removed in the future.
|
|
|
|
Possible values for **progress** are integers from 1 to 100;
|
|
after receiving the value 100, the **application is considered initialized and ready to work**.
|
|
|
|
If at the initialization stage the application has a critical error due to which its further operation is impossible,
|
|
|
|
``"error": "some error"``
|
|
|
|
should be added to the ``OCS request`` for setting progress,
|
|
with a short explanation at what stage this error occurred.
|
|
|
|
Example of request payload with error will look like this::
|
|
|
|
{"progress": 67, "error": "connection error to huggingface."}
|
|
|
|
Enabled
|
|
-------
|
|
|
|
After receiving **progress: 100** (*or when ExApp is not implementing the "/init" endpoint*), AppAPI enables the application.
|
|
|
|
To enable or disable the application, a PUT request is sent to the ``/enabled`` endpoint.
|
|
|
|
.. note:: Unlike using a payload, this request utilizes a query parameter named ``enabled`` to specify the desired state.
|
|
|
|
The ``enabled`` parameter accepts an integer value:
|
|
|
|
* `1` to enable the application
|
|
* `0` to disable the application
|
|
|
|
For example, to enable the application, the request would be::
|
|
|
|
PUT http://expapp:2432/enabled?enabled=1
|
|
|
|
Similarly, to disable the application, the request would be::
|
|
|
|
PUT http://expapp:2432/enabled?enabled=0
|
|
|
|
This approach ensures that the application's state can be easily toggled using a simple query parameter.
|
|
|
|
.. note:: The ``/enabled`` endpoint shares both **enabling** and **disabling**,
|
|
so the app should determine what is going on using the ``enabled`` input parameter of the request.
|
|
|
|
Inside the ``/enabled`` handler, the application should register all actions related to the Nextcloud, such as the UI and other stuff.
|
|
|
|
The response for this request should contain::
|
|
|
|
{"error": ""}
|
|
|
|
for success, and if some error occurs during **enabling**, it should be present and not be empty::
|
|
|
|
{"error": "i can't handle enabling"}
|
|
|
|
This is all three steps involved in the ExApp installation flow.
|