The Setup Architecture of Nextcloud's AppApi Deploy Daemon

2026-03-12T00:00:00+00:00

The Goal

This document explains the required architecture of a Nextcloud installation in order to be able to deploy External Apps (ExApps) via the new AppApi.

This is less of a how-to guide and more about teaching you how to catch fish (docker is a whale... get it?. Sorry)

The setup can be confusing because several containers and services must communicate with each other correctly. This guide aims to provide a clear overview of the required architecture and describes which containers need to connect to each other and how that communication is configured.

The HaRP proxy itself runs in a docker container, but the rest of the parts do not have to. For simplicity's sake however, you can assume that each of the parts listed below runs in its own container.

Prerequisites

Nextcloud: Your nextcloud installation
Reverse Proxy: The web server through which you access nextcloud. Whether Nginx, Apache, Traefik, Caddy, NPM, etc.
HaRP: installed as docker container.
A docker network for ExApps installed by HaRP

A Note

This is one of these things that you have to figure our through trial and error.

After you have installed HaRP, try registering it in your Nextcloud under Admin Settings > AppApi > Deploy Daemon.

Use the "Check Connection" button when registering the daemon to make sure Nextcloud can reach it.
Click the three dots next the deploy daemon and try the "Test Deploy"
Check Nextcloud's Logs while the test deploy runs.
Check the logs from the test container. It is ususally called nc_app_test-deploy. You can use docker logs -f nc_app_test-deploy. This will tell you if the deployed app fails to reach HaRP or Nextcloud.
Check the logs from the HaRP container.

Networking

The reverse proxy obviously must be able to reach both Nextcloud and HaRP.
Nextcloud must be able to reach HaRP, for example internlly on a docker network. HaRP does not care if is it installed on a different host machine than Nextcloud and allows access via HTTPS.
HaRP must be able to reach the apps it deploys. When you register the deploy daemon in Nextcloud, you can specify any docker network to be used for this.
HaRP must be able to access Nextcloud using its public URL. If you are using non-FQDNS, or simply, if HaRP cannot resolve your Nextcloud's URL, make sure to configure its /etc/hosts file or configure the container to use a DNS server which can resolve the domain.
The deployed ExApps must be able to access Nextcloud via the public URL as well.

Reverse Proxy

Routes requsts to Nextcloud: https://cloud.mydomain.com/index.php/...
Routes requests to the subpath /exapps to HaRP at port 8780 (https://cloud.mydomain.com/exapps/...)
Sets correct headers for HaRP: like, Host and X-Forwarded-For

A Diagram

Here is a diagram:

More Details

For more concrete examples and up-to-date documentation, please refer to Nextcloud's HaRP repository here: https://github.com/nextcloud/HaRP

Puzzle of the Egg Basket

2024-04-06T00:00:00+00:00

The Puzzle

A woman goes to the market with a basket full of eggs. On her way, a horse bumps into her, causing her to drop the basket and break all the eggs. The horse's owner feels guilty and asks how many eggs she had so he can compensate her. She replies:

"I don't remember the exact number of eggs, but I do remember this:

When I tried to group the eggs two at a time, there was one egg left over.

The same happened when I grouped them three at a time, four at a time, five at a time, and six at a time—there was always one egg left over.

However, when I grouped them seven at a time, there were no eggs left over."

What is the smallest number of eggs she could have had?

Explanation

We have to search for a number that is divisible by seven but always leaves a remainder of one when divided by $2, 3, 4, 5$, or $6$. So your first question should be: why should such a number exist? Can I define arbitrary conditions of remainders, as above in the puzzle and find solutions for them, or is this puzzle unique in some way?

It is fairly easy to find a number not divisible by any of the integers $2$ to $6$ with a reminder of $1$. Whether it is divisible by $7$, is a different story. An answer to this question is provided by the "Chinese remainder theorem" and I will discuss it a bit further down below.

Keep in mind that solving the puzzle is straightforward, but I’m more interested in a formal approach. Specifically, I’m looking for a method to determine whether a general solution exists, along with a formula or algorithmic approach to compute it.

Naturally, I realize that the abstract mathematical questions I posed above are not the first questions which come to mind when one encounters this puzzle, so I will start by presenting the direct easy solution first.

A naive approach

Consider $6! =720$ which by definition is divisible by the integers $2$ to $6$, and add one to it. Now you have constructed an integer which leaves a remainder of $1$ when divided by $2,3,4,5,$ or $6$ and therefore satisfies the first of the puzzle's conditions. Coincidentally, $(721)$ is also divisible by $7$, but it does not solve the puzzle, because it is not the smallest possible solution.

An educated approach

The idea is simple: compute the least common multiple of the integers $2,3,4,5,6$ and add $1$ to it. Then check whether the result is divisible by 7. If not, find the next smallest common multiple of $2,3,4,5,6$ add 1 to it, then divide by seven and so on. The first number divisible by $7$ is the solution to the puzzle, and it's $301$!

The Mathematics

Let's start by writing the idea above formally. The least common multiple of these integers is:

$$ \text{lcm}(2,3,4,5,6) = 2 \cdot 3 \cdot 2 \cdot 5 = 60 $$

Using a congruence relation, we can write a general form for the solution: The solution - let's call it $x$ - has the form $x = 60n +1$ for the smallest integer $n$ satisfying:

$$ 60n + 1 \equiv 0 \quad (\text{mod} 7) $$

The first multiple of $7$ that can be written in this form is $301$ which we get for $n=5$.

A trick using congruence relations

There is a simple trick that makes use of congruence relations. This trick makes the arithmetic - and therefore the process of trial and error - for finding $n$ a bit easier.

Consider the following equivalent statements:

$$ \begin{aligned} 60 &\equiv 4 \quad &(\text{mod } 7)\\ 60n &\equiv 4n \quad &(\text{mod } 7)\\ 60n + 1 &\equiv 4n +1 \quad &(\text{mod } 7) \end{aligned} $$

The first n which makes $( 4n +1$) divisible by 7 solves the puzzle, which is of course $5$.

Note These statements are equivalent because congruence relations are compatible with algebraic structures. In this case the algebraic structure is the integer ring $\mathbb{Z}$, with the conventional addition and multiplication.

The Chinese Remainder Theorem

Theorem

Given a system of $k$ congruence relations with pairwise coprime moduli $m_1,\cdots, m_k$ then there exists a unique solution up to $ \text{mod } M$, where $M= m_1m_2\cdots m_k$.

$$ \begin{aligned} x &\equiv a_1 \quad &(\text{mod } m_1)\\ x &\equiv a_2 \quad &(\text{mod } m_2)\\ \vdots\\ x &\equiv a_k \quad &(\text{mod } m_k) \end{aligned} $$

Furthermore, if $0 \le a_i \lt m_i: \forall i$, then there exists one and only one $0 \le x \lt M$ and $a_i$ is the remainder of the Euclidean division of $x$ by $m_i$

This is one of multiple possible statements of the theorem. It is of course a modern formulation but the theorem originates from 5th century china, in a book on mathematics. It appeared as conjecture without proof or algorithm.

Great… how does this help us in actually finding the solution? Well, the theorem has a proof by construction. This means that we can prove the theorem by constructing a solution for a general form of the puzzle above.

Proof of existence by construction

Let $M_i = \frac{M}{m_i} = m_1 \cdot m_2 \cdots m_{i-1} \cdot m_{i+1} \cdots m_k$. Since all the moduli $(m_i$) are coprime, then it is easy to see that the greatest common divisor of $(M_i$) and $(m_i$) is $(1$). Write:

$$ \text{gcd}(M_i,m_i) = 1 $$

A well known result in number theory says that if two integers are coprime - as is the case with $(M_i, m_i$), then there exists an integer¹ - call it $x_i$ - such that:

$$ x_iM_i \equiv 1 \quad (\text{mod } m_i) $$

For any other index $j \neq i$, $m_j$ will divide $M_i$ by definition. In other words:

$$ x_iM_i \equiv 0 \quad (\text{mod } m_j)\quad \forall j\neq i $$

This is all we need to construct an integer $x$ which solves the system of congruence relations and proves the theorem. Consider:

$$ x = \sum_{i=1}^{k} x_i M_i a_i $$

and check for any $i$:

$$ \begin{aligned} x \quad \text{mod} \quad m_i &= \sum_{j=1}^{k} x_j M_j a_j \quad &(\text{mod } m_i)\\ &= 0 + 0 + \cdots + x_iM_ia_i + \cdots + 0 \quad &(\text{mod } m_i)\\ &= x_iM_ia_i \quad &(\text{mod } m_i) \end{aligned} $$

so in short: $$ x \equiv x_iM_ia_i \quad (\text{mod } m_i) $$

Since we already know that $x_iM_i \equiv 1 \quad (\text{mod } m_i)$, the equivalence above simplifies to:

$$ x \equiv a_i \quad (\text{mod } m_i) $$

which proves the statement of the theorem.

remarks

In the proof above we have constructed a solution $x$ for a system of congruences. However, our solution still relies on an existence theorem for all the $x_i$. Unless we find a systematic way to compute these integers, we would not be able to find a solution to the puzzle easily.

With that in mind, consider again the statement:

$$ x_iM_i \equiv 1 \quad (\text{mod } m_i) $$

$x_iM_i$ divided by $m_i$ will have a remainder of 1. Meaning that $x_iM_i \pm 1 $ is a multiple of $m_i$.

Write:

$$ \begin{aligned} x_iM_i - 1 &= m_i\\ \end{aligned} $$

Without loss of generality we can write this as:

$$ \begin{equation} 1 = x_iM_i + sm_i \end{equation} $$

Note Note that 1 is the greatest common divisor of $x_iM_i$ and $m_i$ and the equation above is called Bézout's identity.

The factors $x_i, s$ are called Bézout's coefficients, and they are computed using the extended Euclidean algorithm of division at the step before last.

Bézout's identity and the Euclidean algorithm warrant an article by themselves and are therefore beyond the scope of this post.")}}

Application of the theorem

First we need to formulate the puzzle in a way that is compatible with the theorem. We could write:

$$ \begin{aligned} x &\equiv 1 \quad &(\text{mod } 2)\\ x &\equiv 1 \quad &(\text{mod } 3)\\ x &\equiv 1 \quad &(\text{mod } 4)\\ x &\equiv 1 \quad &(\text{mod } 5)\\ x &\equiv 1 \quad &(\text{mod } 6)\\ x &\equiv 0 \quad &(\text{mod } 7)\\ \end{aligned} $$

We can improve on this by using the least common multiple of these integers,$60$, since it encodes the first five congruences:

$$ \begin{aligned} x &\equiv 1 \quad &(\text{mod } 60)\\ x &\equiv 0 \quad &(\text{mod } 7)\\ \end{aligned} $$

$60$ and $7$ are coprime, and the divisors $1$ and $0$ are less than $60$ and $7$ respectively. Applying the theorem, the solution becomes:

$$ x \equiv x_1 M_1 a_1 + x_2 M_2 a_2 \quad (\text{mod } 7\cdot60) $$

where

$$ \begin{aligned} M_1 &= 7\\ M_2 &= 60\\ a_1 &= 1\\ a_2 &= 0\\ \end{aligned} $$

$$ \Rightarrow x \equiv 7x_1 + 0 \quad (\text{mod } 420) $$

Now it only remains to compute Bézout's coefficients for the identity:

$$ 1 = 7x_1 + s60 $$

As mentioned before, those coefficients are computed from the Euclidean algorithm of division. In this case we have:

$$ 1 = 7(-17) + (2)60 $$

$$ \Rightarrow x \equiv -119 \quad (\text{mod } 420) $$

The solution $x$ is unique up to modulo $420$, meaning that there are multiple solutions, which are $420$ apart. We know from the theorem that there is one and only one solution between $0$ and $420$:

$$ \Rightarrow \boxed{x = -119 + 420 = 301} $$

$(x_i)$ is called a modular multiplicative inverse of $M_i$, and it exists if and only iff both integers are coprime.

(KiB)ibytium

The Setup Architecture of Nextcloud's AppApi Deploy Daemon

Puzzle of the Egg Basket