Nextcloud¶
Description¶
Elevate your collaboration with Nextcloud, a vibrant self-hosted cloud solution designed for dynamic file sharing, seamless communication, and effortless teamwork. Nextcloud offers a full suite of integrated tools (including LDAP and OIDC authentication, Redis caching, and automated plugin management via OCC) to empower a secure, extensible, and production-ready cloud environment.
Overview¶
This role provisions a complete Nextcloud deployment using Docker Compose. It automates the setup of the Nextcloud application along with its underlying MariaDB database and configures the system for secure public access via an NGINX reverse proxy. The deployment includes automated configuration merging into config.php, health check routines, and integrated support for backup and recovery operations.
Cosmos¶
The diagram places Nextcloud in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).
flowchart LR
subgraph deps [Dependencies]
dep_svc_ai_litellm["svc-ai-litellm 🐳🐝"]
dep_svc_bkp_volume_2_local["svc-bkp-volume-2-local 💻"]
dep_svc_db_mariadb["svc-db-mariadb 🐳🐝"]
dep_svc_db_openldap["svc-db-openldap 🐳🐝"]
dep_svc_db_redis["svc-db-redis 🐳🐝"]
dep_svc_net_tor["svc-net-tor 🐳🐝"]
dep_web_app_bigbluebutton["web-app-bigbluebutton 🐳🐝"]
dep_web_app_dashboard["web-app-dashboard 🐳🐝"]
dep_web_app_discourse["web-app-discourse 🐳🐝"]
dep_web_app_gitlab["web-app-gitlab 🐳🐝"]
dep_web_app_hermes["web-app-hermes 🐳🐝"]
dep_web_app_keycloak["web-app-keycloak 🐳🐝"]
dep_web_app_mastodon["web-app-mastodon 🐳🐝"]
dep_web_app_matomo["web-app-matomo 🐳🐝"]
dep_web_app_matrix["web-app-matrix 🐳🐝"]
dep_web_app_mattermost["web-app-mattermost 🐳🐝"]
dep_web_app_openclaw["web-app-openclaw 🐳🐝"]
dep_web_app_openproject["web-app-openproject 🐳🐝"]
dep_web_app_openwebui["web-app-openwebui 🐳🐝"]
dep_web_app_peertube["web-app-peertube 🐳🐝"]
dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
dep_web_app_seaweedfs["web-app-seaweedfs 🐳🐝"]
dep_web_app_stalwart["web-app-stalwart 🐳🐝"]
dep_web_app_xwiki["web-app-xwiki 🐳🐝"]
dep_web_app_zammad["web-app-zammad 🐳🐝"]
dep_web_svc_collabora["web-svc-collabora 🐳🐝"]
dep_web_svc_coturn["web-svc-coturn 🐳🐝"]
dep_web_svc_css["web-svc-css 💻"]
dep_web_svc_logout["web-svc-logout 🐳🐝"]
dep_web_svc_onlyoffice["web-svc-onlyoffice 🐳🐝"]
end
subgraph role [web-app-nextcloud 🐳🐝]
svc_sso["sso"]
svc_coturn["coturn"]
svc_logout["logout"]
svc_ldap["ldap"]
svc_dashboard["dashboard"]
svc_matomo["matomo"]
svc_email["email"]
svc_redis["redis"]
svc_mariadb["mariadb"]
svc_nextcloud["nextcloud"]
svc_proxy["proxy"]
svc_context_agent["context_agent"]
svc_contextagentmcp["contextagentmcp"]
svc_cron["cron"]
svc_talk["talk"]
svc_whiteboard["whiteboard"]
svc_onlyoffice["onlyoffice"]
svc_collabora["collabora"]
svc_bigbluebutton["bigbluebutton"]
svc_xwiki["xwiki"]
svc_minio["minio ❌"]
svc_seaweedfs["seaweedfs"]
svc_talk_recording["talk_recording"]
svc_css["css"]
svc_hcaptcha["hcaptcha"]
svc_prometheus["prometheus"]
svc_tor["tor"]
svc_openproject["openproject"]
svc_gitlab["gitlab"]
svc_discourse["discourse"]
svc_mattermost["mattermost"]
svc_matrix["matrix"]
svc_zammad["zammad"]
svc_openwebui["openwebui"]
svc_litellm["litellm"]
svc_mastodon["mastodon"]
svc_peertube["peertube"]
svc_moodle["moodle ❌"]
svc_suitecrm["suitecrm ❌"]
svc_container_backup["container_backup"]
svc_hermes["hermes"]
svc_openclaw["openclaw"]
svc_flowise["flowise ❌"]
end
dep_svc_ai_litellm -. "0..1" .-> svc_litellm
dep_svc_bkp_volume_2_local -. "0..1" .-> svc_container_backup
dep_svc_db_mariadb -. "0..1" .-> svc_mariadb
dep_svc_db_openldap -. "0..1" .-> svc_ldap
dep_svc_db_redis -. "0..1" .-> svc_redis
dep_svc_net_tor -. "0..1" .-> svc_tor
dep_web_app_bigbluebutton -. "0..1" .-> svc_bigbluebutton
dep_web_app_dashboard -. "0..1" .-> svc_dashboard
dep_web_app_discourse -. "0..1" .-> svc_discourse
dep_web_app_gitlab -. "0..1" .-> svc_gitlab
dep_web_app_hermes -. "0..1" .-> svc_hermes
dep_web_app_keycloak -. "0..1" .-> svc_sso
dep_web_app_mastodon -. "0..1" .-> svc_mastodon
dep_web_app_matomo -. "0..1" .-> svc_matomo
dep_web_app_matrix -. "0..1" .-> svc_matrix
dep_web_app_mattermost -. "0..1" .-> svc_mattermost
dep_web_app_openclaw -. "0..1" .-> svc_openclaw
dep_web_app_openproject -. "0..1" .-> svc_openproject
dep_web_app_openwebui -. "0..1" .-> svc_openwebui
dep_web_app_peertube -. "0..1" .-> svc_peertube
dep_web_app_prometheus -. "0..1" .-> svc_prometheus
dep_web_app_seaweedfs -. "0..1" .-> svc_seaweedfs
dep_web_app_stalwart -. "0..1" .-> svc_email
dep_web_app_xwiki -. "0..1" .-> svc_xwiki
dep_web_app_zammad -. "0..1" .-> svc_zammad
dep_web_svc_collabora -. "0..1" .-> svc_collabora
dep_web_svc_coturn -. "0..1" .-> svc_coturn
dep_web_svc_coturn -. "0..1" .-> svc_talk
dep_web_svc_css -. "0..1" .-> svc_css
dep_web_svc_logout -. "0..1" .-> svc_logout
dep_web_svc_onlyoffice -. "0..1" .-> svc_onlyoffice
Solid 1:1 edges are fixed relationships; dashed 0..1 edges are conditional (enabled only in matching deployments); red 0..0 edges are turned off in this role. Node markers show the role’s deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in meta/main.yml.
Features¶
Fully Dockerized Deployment: Simplifies installation using Docker Compose for the Nextcloud application and its MariaDB backend.
Secure Access: Integrates with an NGINX reverse proxy for encrypted, high-performance access.
Robust Authentication: Supports LDAP and OIDC for secure identity and access management.
Automated Configuration Management: Uses additive configuration files to dynamically merge system settings into
config.php.Integrated Backup & Recovery: Provides built-in support for backup and restoration operations to safeguard your data.
Extensible Plugin Framework: Easily manage and configure hundreds of Nextcloud plugins using the OCC command line tool.
Quick Setup¶
Development¶
Clone, set up the workstation, and deploy Nextcloud onto the local stack:
git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-app-nextcloud full_cycle=false
Production¶
Run the published image to provision the inventory and deploy Nextcloud to a managed server (the mounted volume persists the inventory):
APP=web-app-nextcloud
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"
docker run --rm -it \
-v "$PWD/inventories:/etc/infinito.nexus/inventories" \
-e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
ghcr.io/infinito-nexus/core/debian bash -c '
INVENTORY=/etc/infinito.nexus/inventories/production
infinito administration inventory provision "$INVENTORY" \
--inventory-file "$INVENTORY/devices.yml" \
--host "$HOST" \
--include "$APP" \
--vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
infinito administration deploy dedicated "$INVENTORY/devices.yml" \
--password-file "$INVENTORY/.password" \
--diff -vv'
Addons¶
The config-bearing Nextcloud apps are declared in meta/addons/ under the unified addon contract (requirement 026).
Each declaration carries its full occ config:app:set payload under config:.
The enable-only appstore apps stay under nextcloud.plugins in meta/services.yml.
Addon |
Mechanism |
Default state |
Bridges |
|---|---|---|---|
|
|
enabled when the SSO OIDC plugin selector picks it |
|
|
|
enabled with the |
|
|
|
enabled with the |
|
|
|
enabled with the |
|
|
|
enabled with the |
|
|
|
enabled with the |
|
|
|
|
none (self-hosted backend) |
|
|
enabled with the |
|
The SSO (sociallogin) and LDAP (user_ldap) login surfaces are covered by the OIDC/LDAP Playwright specs (requirements 017/018).
MCP Server¶
Nextcloud serves a Model Context Protocol endpoint through the AppAPI proxy of the context_agent ExApp.
Property |
Value |
|---|---|
Endpoint |
|
Container-network URL |
|
Transport |
Streamable HTTP |
Exposure |
internal (the sidecar is reachable on the container network only; the hub’s own MCP route is not published to clients) |
Auth |
|
Identity |
the Nextcloud account the app password belongs to; every tool call the adapter forwards runs with that account’s permissions |
Implementation |
adapter ( |
Default state |
off; |
Deployment¶
The context_agent and contextagentmcp services in meta/services.yml render only while mcp.enabled is true. The first runs ghcr.io/nextcloud/context_agent, listens on its internal port for AppAPI only, and shares credentials.context_agent_app_secret with the ExApp registration as APP_SECRET. The second is the adapter sidecar, built from the staged svc-ai-mcp-adapter context, read-only with every capability dropped, and it is the only MCP endpoint clients are given.
The sidecar reads its upstream credential from an upstream.env file rather than from the compose environment, because the app password does not exist when the stack is first rendered. tasks/utils/mcp.yml writes that file after the mint and recreates the sidecar through svc-ai-mcp-adapter’s rebuild.yml: compose up resolves env_file while creating the container, which a restart would not.
tasks/utils/mcp.yml waits for the ExApp heartbeat, registers the deploy daemon and the ExApp (route ^/mcp, verbs POST,GET,DELETE, access level 1), enables the ExApp, mints an app password for the dedicated MCP account via occ user:auth-tokens:add, persists it through sys-token-store under users['mcp-web-app-nextcloud'].tokens['web-app-nextcloud'], and asserts that an authenticated initialize call answers 200.
Tool categories¶
The 2.7.0 image ships 23 tool categories, which are application names (calendar, files, mail, talk, …) rather than operations: each bundles its read and its write tools, and the hub offers no setting that removes only the mutating ones. Enabling the ExApp writes true for every category absent from tool_status, so the hub itself serves all of them, write tools included.
The adapter is what bounds that. files/mcp/tools.json names the nine read tools of calendar, contacts and files — the three categories whose upstream is_available is unconditional, so the set does not vary with which optional apps a deployment installs. svc-ai-mcp-adapter refuses any tool outside that list and any tool marked mutating while mutating_tools_enabled is false, and it refuses to start at all if the contract’s schema_sha256 does not match the file. The refusal happens in the sidecar, so it holds for every client regardless of what each renders locally.
The hub keeps all its categories. Nextcloud’s own Assistant is unaffected by the bound: it reads the same tool_status, and nothing here narrows it.
The app password never reaches a client. Clients present credentials.mcp_bearer to the sidecar; the sidecar presents the app password upstream. Revoking one does not revoke the other.
occ app_api:app:config:get context_agent tool_status
occ app_api:app:config:set context_agent tool_status --value '<json map of category to bool>'
Widening the exposed set means adding the tool to files/mcp/tools.json, recomputing both adapter.specification_sha256 and tools.schema_sha256, and listing it in mcp.tools.allowlist.
Verification¶
The sidecar is reachable on the container network only, so a client probes it from inside the stack:
curl -i -X POST \
-H 'Authorization: Bearer <credentials.mcp_bearer>' \
-H 'Accept: application/json, text/event-stream' \
-H 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"1"}}}' \
http://contextagentmcp:8080/mcp
From outside, every MCP path answers 404. The hub serves its route under two spellings — with and without the /index.php front controller — and roles/sys-svc-proxy/templates/mcp/vhost.conf.j2 withdraws both, so neither reaches the Context Agent. files/playwright/test-mcp-guest.js probes all three public paths and asserts each answers >= 300 without an MCP protocol body.
Default state¶
Off. mcp.enabled is true only while web-app-hermes, web-app-openclaw or web-app-openwebui is part of the deployment.
How to disable¶
Remove the MCP client roles, or pin mcp.enabled: false for this role. The context_agent service is then not rendered, the ExApp is not registered with AppAPI, and no app password is minted.
Documentation¶
A detailed documentation for the use and administration of Nextcloud on Infinito.Nexus you will find here.
Further Resources¶
Persona contract opt-outs¶
The shared biber and administrator persona helpers are declared blocked in templates/playwright.env.j2. Nextcloud presents three different login surfaces depending on the variant (native, oidc_login, sociallogin), the native administrator authenticates with the role-local credentials.administrator_password rather than the Keycloak secret, and the #firstrunwizard modal intercepts the user-menu click the generic logout depends on. Both personas are therefore driven by the role’s own login specs — test-login-admin-native.js, test-login-admin-oidc.js, test-login-biber-oidc.js and test-login-biber-ldap.js under files/playwright — which carry the flavor switch, the modal dismissal and the login retry the shared helper lacks.
Credits¶
Implemented by Kevin Veen-Birkenbach. Part of the Infinito.Nexus Project and maintained by Kevin Veen-Birkenbach. Licensed under the Infinito.Nexus Community License (Non-Commercial).