Skip to content

Commit 205299d

Browse files
tzerbertzerber
committed
Add initial AppApi basic example
Signed-off-by: Kaloyan Nikolov <tzerber@gmail.com>
1 parent 145c97a commit 205299d

4 files changed

Lines changed: 1340 additions & 0 deletions

File tree

‎.examples/appapi/Dockerfile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
FROM nextcloud:stable-fpm
2+
RUN apt-get update && apt-get install -y ffmpeg python3.13-venv nano pipx
3+
ADD ./poetry.sh /tmp/poetry.sh
4+
USER www-data
5+
RUN pipx ensurepath
6+
RUN python3 /tmp/poetry.sh
7+
USER root

‎.examples/appapi/README.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Nextcloud AppAPI (HaRP) – Docker Compose Example
2+
(FPM + Nginx + nginx-proxy-manager)
3+
4+
> **Warning**
5+
> This example is based on a working setup but differs from other examples. Review the differences carefully before adapting it to your environment.
6+
7+
This document provides a minimal example of running the AppAPI container required for Nextcloud 32 or newer using Docker Compose.
8+
9+
The setup assumes:
10+
11+
- `nginx-proxy-manager` as the external reverse proxy
12+
- `nginx` + `php-fpm` (FPM variant of Nextcloud)
13+
- A dedicated external proxy network
14+
15+
This configuration differs from other examples because it uses a separate proxy network. Review the network definitions carefully before deploying.
16+
17+
This example must be significantly adapted if you intend to run Nextcloud with Apache.
18+
19+
AppAPI requires Poetry. This example includes a modified Dockerfile that installs Poetry on top of the stable FPM image. It has been tested with:
20+
21+
- `nextcloud:32.0.6-fpm`
22+
23+
Additional information about AppAPI can be found in the official documentation:
24+
25+
https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html
26+
27+
The Poetry installer script is taken from:
28+
29+
https://install.python-poetry.org/
30+
31+
This example uses the latest `stable-fpm` variant of Nextcloud.
32+
33+
Contributions and improvements are welcome.
34+
35+
---
36+
37+
# Dockerfile
38+
39+
```Dockerfile
40+
FROM nextcloud:stable-fpm
41+
42+
RUN apt-get update && apt-get install -y python3.13-venv pipx
43+
44+
ADD ./poetry.sh /tmp/poetry.sh
45+
46+
USER www-data
47+
RUN pipx ensurepath
48+
RUN python3 /tmp/poetry.sh
49+
50+
USER root
51+
```
52+
53+
This Dockerfile:
54+
55+
- Extends the `stable-fpm` image
56+
- Installs Python venv support and `pipx`
57+
- Installs Poetry as the `www-data` user
58+
- Switches back to `root` for standard container behavior
59+
60+
---
61+
62+
# Docker Compose Example
63+
64+
```yaml
65+
services:
66+
db:
67+
image: postgres:16-alpine
68+
restart: unless-stopped
69+
volumes:
70+
- db:/var/lib/postgresql/data:Z
71+
environment:
72+
- POSTGRES_PASSWORD=CHANGEME
73+
- POSTGRES_DB=nextcloud
74+
- POSTGRES_USER=nextcloud
75+
76+
app:
77+
build: ./
78+
restart: unless-stopped
79+
volumes:
80+
- nextcloud:/var/www/html
81+
- /var/run/docker.sock:/var/run/docker.sock
82+
networks:
83+
- default
84+
- appapi
85+
environment:
86+
- REDIS_HOST=redis
87+
- POSTGRES_HOST=db
88+
- POSTGRES_PASSWORD=CHANGEME
89+
- POSTGRES_DB=nextcloud
90+
- POSTGRES_USER=nextcloud
91+
depends_on:
92+
- db
93+
- redis
94+
95+
redis:
96+
image: redis:alpine
97+
restart: unless-stopped
98+
99+
web:
100+
image: nginx:alpine
101+
restart: unless-stopped
102+
hostname: web
103+
volumes:
104+
- nextcloud:/var/www/html:ro
105+
- ./nginx.conf:/etc/nginx/nginx.conf:ro # https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html
106+
expose:
107+
- 80
108+
depends_on:
109+
- app
110+
networks:
111+
- default
112+
- proxy
113+
- appapi
114+
115+
cron:
116+
build: ./
117+
restart: unless-stopped
118+
networks:
119+
- default
120+
- appapi
121+
volumes:
122+
- nextcloud:/var/www/html
123+
entrypoint: /cron.sh
124+
depends_on:
125+
- db
126+
- redis
127+
128+
appapi:
129+
platform: linux/amd64
130+
container_name: appapi
131+
hostname: appapi
132+
privileged: true
133+
image: ghcr.io/nextcloud/nextcloud-appapi-harp:release
134+
networks:
135+
- proxy
136+
- appapi
137+
restart: unless-stopped
138+
depends_on:
139+
- app
140+
# env_file:
141+
# - appapi.env
142+
environment:
143+
# NC_HAPROXY_PASSWORD needs to be at least 12 chars long. This variable exists for backward compatibility with the DSP image
144+
# ToDo: verify whether this variable is still required
145+
- NC_HAPROXY_PASSWORD=CHANGEME1234
146+
# HP_SHARED_KEY needs to be at least 12 chars long.
147+
- HP_SHARED_KEY=CHANGEME1234
148+
# NC_INSTANCE_URL must be the externally accessible URL of the Nextcloud instance
149+
- NC_INSTANCE_URL=https://external-nextcloud.url
150+
volumes:
151+
- /var/run/docker.sock:/var/run/docker.sock
152+
153+
volumes:
154+
db:
155+
nextcloud:
156+
157+
networks:
158+
proxy: # This is an external network created for nginx-proxy-manager used by this setup. It must be edited to match your environment.
159+
name: proxy-manager_proxy_network
160+
external: true
161+
162+
appapi: # This network is required in order for AppAPI to function correctly. Using "host" networking as in some examples may fail.
163+
name: appapi_network
164+
```
165+
166+
---
167+
168+
# Architecture Overview
169+
170+
_Mermaid diagrams may render inconsistently depending on the viewer._
171+
172+
```mermaid
173+
graph TD
174+
subgraph Proxy Stack
175+
Proxy[Proxy Container]
176+
ProxyNet
177+
end
178+
179+
subgraph Nextcloud Stack
180+
NC-Cron
181+
NC-Main
182+
DB
183+
Web
184+
Redis
185+
AppApiHaRP[AppAPI Container]
186+
NCNet
187+
AppApiNet[AppAPI Network]
188+
end
189+
190+
ProxyNet[Proxy Network]
191+
NCNet[Nextcloud Internal Network]
192+
Internet[Internet]
193+
194+
Internet --- |HTTPS| ProxyNet
195+
ProxyNet ---|HTTPS| Internet
196+
ProxyNet --- Proxy
197+
Proxy --- ProxyNet
198+
NCNet --- ProxyNet
199+
NCNet --- Redis
200+
Redis --- NCNet
201+
ProxyNet --- NCNet
202+
NC-Cron --- NCNet
203+
NC-Main --- NCNet
204+
DB --- NCNet
205+
NCNet --- NC-Cron
206+
NCNet --- NC-Main
207+
NCNet --- DB
208+
NCNet --- AppApiHaRP
209+
AppApiHaRP --- NCNet
210+
AppApiNet --- AppApiHaRP
211+
AppApiHaRP --- AppApiNet
212+
AppApiNet --- ProxyNet
213+
ProxyNet --- AppApiNet
214+
Web --- NCNet
215+
NCNet --- Web
216+
```
217+
218+
---
219+
220+
# Nextcloud AppAPI Daemon Configuration
221+
222+
To make the above compose file functional, configure the daemon in the Nextcloud admin interface.
223+
224+
Navigate to:
225+
226+
**Admin Settings → AppAPI → Register Daemon**
227+
228+
## Base Configuration
229+
230+
| Field | Value |
231+
|--------|--------|
232+
| Daemon configuration template | HaRP Proxy (Docker) |
233+
| Name | harp_proxy_host |
234+
| Display name | HaRP Proxy (Host) |
235+
| Deployment method | docker-install |
236+
| HaRP host | appapi:8780 |
237+
| HaRP shared key | Value of `HP_SHARED_KEY` |
238+
| Nextcloud URL | Value of `NC_INSTANCE_URL` |
239+
| Set as default daemon | Enabled |
240+
241+
Click **Show Deploy Config**, then configure:
242+
243+
## Deploy Configuration
244+
245+
| Field | Value |
246+
|--------|--------|
247+
| Enable HaRP | Enabled |
248+
| FRP server address | appapi:8782 |
249+
| Docker socket proxy port | 24000 |
250+
| Disable FRP | Disabled |
251+
| Docker network | appapi |
252+
| Compute device | CPU |
253+
254+
After completing the configuration:
255+
256+
1. Click **Check Connection**
257+
2. Verify the connection succeeds
258+
3. Click **Register**
259+
260+
---
261+
262+
# Validation
263+
264+
After registering the daemon:
265+
266+
1. Start a test deployment from the AppAPI interface.
267+
2. The deployment should complete within approximately 2–3 minutes.
268+
269+
---
270+
271+
# Intended Audience
272+
273+
This example assumes:
274+
275+
- Familiarity with Docker Compose
276+
- Understanding of reverse proxy networking
277+
- Knowledge of FPM-based Nextcloud deployments
278+
- Ability to adapt networks and environment variables to existing infrastructure
279+
280+
This is not intended as a beginner-level guide.

‎.examples/appapi/compose.yaml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
services:
2+
db:
3+
image: postgres:16-alpine
4+
restart: unless-stopped
5+
volumes:
6+
- db:/var/lib/postgresql/data:Z
7+
environment:
8+
- POSTGRES_PASSWORD=CHANGEME
9+
- POSTGRES_DB=nextcloud
10+
- POSTGRES_USER=nextcloud
11+
12+
app:
13+
build: ./
14+
restart: unless-stopped
15+
volumes:
16+
- nextcloud:/var/www/html
17+
- /var/run/docker.sock:/var/run/docker.sock
18+
networks:
19+
- default
20+
- appapi
21+
environment:
22+
- REDIS_HOST=redis
23+
- POSTGRES_HOST=db
24+
- POSTGRES_PASSWORD=CHANGEME
25+
- POSTGRES_DB=nextcloud
26+
- POSTGRES_USER=nextcloud
27+
depends_on:
28+
- db
29+
- redis
30+
31+
redis:
32+
image: redis:alpine
33+
restart: unless-stopped
34+
35+
web:
36+
image: nginx:alpine
37+
restart: unless-stopped
38+
hostname: web
39+
volumes:
40+
- nextcloud:/var/www/html:ro
41+
- ./nginx.conf:/etc/nginx/nginx.conf:ro # https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html
42+
expose:
43+
- 80
44+
depends_on:
45+
- app
46+
networks:
47+
- default
48+
- proxy
49+
- appapi
50+
51+
cron:
52+
build: ./
53+
restart: unless-stopped
54+
networks:
55+
- default
56+
- appapi
57+
volumes:
58+
- nextcloud:/var/www/html
59+
entrypoint: /cron.sh
60+
depends_on:
61+
- db
62+
- redis
63+
64+
appapi:
65+
platform: linux/amd64
66+
container-name: appapi
67+
hostname: appapi
68+
privileged: true
69+
image: ghcr.io/nextcloud/nextcloud-appapi-harp:release
70+
networks:
71+
- proxy
72+
- appapi
73+
restart: unless-stopped
74+
depends_on:
75+
- app
76+
#env_file:
77+
# - appapi.env
78+
environment:
79+
- NC_HAPROXY_PASSWORD=CHANGEME # this needs to be at least 12 chars long. This exists for backward compatibility with the DSP image, it might be removed in the future from this example.
80+
- HP_SHARED_KEY="CHANGEME" # this needs to be at least 12 chars long
81+
- NC_INSTANCE_URL="https://external-nextcloud.url"
82+
volumes:
83+
- /var/run/docker.sock:/var/run/docker.sock
84+
85+
volumes:
86+
db:
87+
nextcloud:
88+
89+
networks:
90+
proxy: # This is external network, created for nginx-proxy-manager used by this setup.
91+
name: proxy-manager_proxy_network
92+
external: true
93+
appapi: # this is required in order for appapi to work
94+
name: appapi_network

0 commit comments

Comments
 (0)