diff --git a/README.md b/README.md index bcb2750c..46f1b806 100644 --- a/README.md +++ b/README.md @@ -8,42 +8,103 @@ [![Tests - Deploy](https://github.com/nextcloud/app_api/actions/workflows/tests-deploy.yml/badge.svg)](https://github.com/nextcloud/app_api/actions/workflows/tests-deploy.yml) [![Tests](https://github.com/nextcloud/app_api/actions/workflows/tests.yml/badge.svg)](https://github.com/nextcloud/app_api/actions/workflows/tests.yml) -### Supercharge your Nextcloud with AppAPI and applications specifically designed for it. +AppAPI is the Nextcloud component that enables **External Apps (ExApps)**. -### This project pivots on four main pillars: +ExApps are Nextcloud apps whose backend runs **outside** the Nextcloud PHP process (typically as a Docker +container). AppAPI provides the APIs and lifecycle management so these external backends can still +integrate with Nextcloud users, permissions and the web UI. -1. **Enhanced stability** This ecosystem is committed to maintaining API stability over extended periods. - This ensures a reliable and consistent user experience as developers won't need to constantly update their apps with each new release. +AppAPI is **only useful if you want to install or develop External Apps**. -2. **Enhanced security** Unlike the traditional method, which allowed direct interaction with the core Nextcloud code, this approach uses controlled APIs to manage access, ensuring greater application stability and delivering a more focused user experience. +## If you are here because of the warning “default deploy daemon is not set” -3. **Reliable computing power** The ecosystem is designed to solve resource-intensive problems. - Developers can easily integrate complex computing functions, including advanced machine learning models, and run them on external hardware. +You might have seen this in the admin overview/security checks: -4. **Community friendly** The project aims to attract a diverse and broader developer community by creating applications - in various programming languages and providing a well-documented, consistent and user-friendly API. - Community collaboration and contributions are encouraged to drive open source innovation. +> AppAPI default deploy daemon is not set. Please register a default deploy daemon … + +This warning means: + +- AppAPI is enabled, **but no Deploy Daemon is configured**, so Nextcloud cannot install/run External Apps yet. + +You have two valid options: + +1. **You do not want External Apps** + - Disable AppAPI in **Apps → Tools → AppAPI**, or with: + - `occ app:disable app_api` + - The warning will disappear. + +2. **You want to install External Apps** + - Open **Settings → Administration → AppAPI** + - Register a Deploy Daemon and set it as the default + - Use **Check connection** and **Test deploy** to verify the setup + +## Key concepts (short glossary) + +- **External App (ExApp)**: a Nextcloud app where the backend runs as a separate service (usually a container), + but is still installed/managed from Nextcloud and integrates with the Nextcloud UI. +- **Deploy Daemon**: the service Nextcloud talks to in order to install, start/stop, and reach ExApps. + Without a Deploy Daemon, AppAPI cannot deploy ExApps. + +## Deploy Daemon options + +### HaRP (recommended for Nextcloud 32+) + +**HaRP** (High-performance AppAPI Reverse Proxy) is the newer and recommended Deploy Daemon. +It is a reverse proxy system designed specifically for ExApps: + +- Proxies access to the Docker Engine used to create ExApp containers +- Routes requests directly to ExApps (bypassing the Nextcloud PHP process), improving performance and enabling WebSockets +- Uses FRP (Fast Reverse Proxy) tunnels so ExApp containers do not need to expose ports to the host — this simplifies networking and provides NAT traversal + +Repository: https://github.com/nextcloud/HaRP + +### Docker Socket Proxy (DSP) — legacy + +**Docker Socket Proxy** (often shortened as **DSP**) is the classic Deploy Daemon implementation. +It is a security-hardened proxy in front of the Docker Engine socket/API and is protected by basic +authentication and brute-force protection. + +> **Note:** DSP is being deprecated in favor of HaRP and is scheduled for removal in Nextcloud 35. +> New installations should use HaRP. + +Repository: https://github.com/nextcloud/docker-socket-proxy + +## Security notes (for administrators) + +Configuring a Deploy Daemon means allowing Nextcloud to orchestrate application containers. Keep these points in mind: + +- Run HaRP/DSP in a trusted network and do not expose it to the public internet. +- Use strong secrets (`HP_SHARED_KEY` for HaRP, `NC_HAPROXY_PASSWORD` for DSP). +- For remote setups or untrusted networks, use TLS where supported and restrict access with firewall rules. +- Only deploy ExApps you trust, and keep their images up to date. + +## Why AppAPI exists (what it is useful for) + +AppAPI is designed to make it easier to build and run ExApps in a way that is: + +1. **Stable for admins**: ExApps integrate through defined interfaces instead of tightly coupling to server internals. +2. **More isolated**: ExApps run out-of-process and interact with Nextcloud through controlled APIs. +3. **Suitable for heavy workloads**: ExApps can run on separate hardware (including GPU-enabled hosts). +4. **Language-friendly**: ExApps can be written in languages other than PHP (Python/Node/Go/…). ## Documentation Latest documentation can be found here: -1. Admin manual: [ExApps management](https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/index.html) -2. Developer manual: [ExApp development](https://docs.nextcloud.com/server/latest/developer_manual/exapp_development/index.html) +1. Admin manual: + - AppAPI and External Apps: https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html + - Deployment configurations: https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/DeployConfigurations.html +2. Developer manual: + - ExApp development: https://docs.nextcloud.com/server/latest/developer_manual/exapp_development/index.html ### Support We appreciate any support for this project: -- ⭐ Star our work on GitHub (it helps us a lot) -- ❗ Create an Issue or feature request (bring to us an excellent idea) -- 💁 Resolve an Issue and create a Pull Request (contribute to this project) -- 🧑‍💻 Develop your own application using AppAPI and share it with the world (contact us if help is needed) - -In conclusion, we are genuinely excited about the future of the AppAPI project and its potential to transform -the way applications are developed and experienced within Nextcloud. +- ⭐ Star our work on GitHub +- ❗ Create an issue or feature request +- 💁 Resolve an issue and open a pull request +- 🧑‍💻 Build and publish ExApps using AppAPI -As we embark on this journey, we warmly invite you - developers, thinkers, creators, and visionaries - -to join us in shaping a more versatile, stable, and secure app landscape. -#### Your insights, suggestions, and contributions are invaluable to us. +Thank you for helping improve ExApps and their ecosystem. diff --git a/appinfo/info.xml b/appinfo/info.xml index 56e164b3..a5070ee9 100644 --- a/appinfo/info.xml +++ b/appinfo/info.xml @@ -9,34 +9,33 @@ Nextcloud AppAPI "AppAPI default deploy daemon is not set …" -We appreciate any support for this project: +That warning means: "External Apps are not configured yet". -- ⭐ Star our work on GitHub -- ❗ Create an Issue or feature request -- 💁 Resolve an Issue and create a Pull Request -- 🧑‍💻 Develop your own application using AppAPI +You can either disable AppAPI, or configure a Deploy Daemon (see below). -We are genuinely excited about the future of the AppAPI project and its potential to transform -the way applications are developed and experienced within Nextcloud. +### How do External Apps get deployed? -As we embark on this journey, we warmly invite you - developers, thinkers, creators, and visionaries - -to join us in shaping a more versatile, stable, and secure app landscape. +A **Deploy Daemon** is the service Nextcloud talks to in order to install, start, stop and reach ExApps. -*Your insights, suggestions, and contributions are invaluable to us.* +Two options are available: +- **HaRP** (recommended for Nextcloud 32+) — a high-performance reverse proxy with FRP tunneling +- **Docker Socket Proxy** (legacy) — scheduled for removal in Nextcloud 35 + +See the [admin documentation](https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/DeployConfigurations.html) for setup instructions. ]]> 33.0.0-dev.0 agpl @@ -44,7 +43,8 @@ to join us in shaping a more versatile, stable, and secure app landscape. Alexander Piskun AppAPI - https://docs.nextcloud.com/server/latest/developer_manual/exapp_development + https://docs.nextcloud.com/server/latest/admin_manual/exapps_management/AppAPIAndExternalApps.html + https://docs.nextcloud.com/server/latest/developer_manual/exapp_development/index.html integration tools