Nextcloud Dev Setup

Nextcloud development environment setup

Builds a disposable local Nextcloud development environment on nextcloud-docker-dev, then layers everything ExApp development needs on top: AppAPI enabled, a HaRP deploy daemon (production-like docker-install) plus a manual-install daemon (fast loop), /exapps/ routed through the bundled nginx proxy, and a real reference ExApp deployed as proof the whole chain works.

How to execute

Read references/dev-environment.md in full, then execute its stages 1 to 7 in order. Every stage ends with a Verify block; do not continue past a failed Verify (each has a matching "If it fails" entry). Stage 7, deploying the bundled minimal_exapp through HaRP, is the acceptance gate: when its endpoints answer over http://nextcloud.local/exapps/..., the environment is done.

Rules that prevent the common disasters

• Never run docker compose down -v and never delete workspace/ or named volumes without explicit human approval; they hold every instance's data.
• Never edit tracked files of the nextcloud-docker-dev checkout. The whole AppAPI overlay lives in untracked files (.env, docker-compose.override.yml, data/nginx/vhost.d/).
• The HaRP shared key must be byte-identical between the compose override (HP_SHARED_KEY) and the daemon:register --harp_shared_key value; a mismatch is the number one install failure.
• After creating a new data/nginx/vhost.d/<host> file, docker compose restart proxy; a plain nginx reload never picks up a file that did not exist when the config was generated.
• Kill development processes by exact PID only, and use dev-only secrets you never reuse elsewhere.

Files

• references/dev-environment.md: the full staged runbook (bring-up, daemons, smoke test, an optional browser for the agent, daily operation, reset and recovery, troubleshooting).
• references/macos.md: read first on a Mac. Verified end to end on Apple Silicon: what genuinely differs, which ExApp images have arm64 builds, the Docker socket, and the adjustments you do not need.
• assets/macos-preflight.sh: checks a Mac and prints the .env lines to use.
• Next steps: build your own ExApp with the exapp-development skill; operate a real instance with exapp-operations.