Qortal-Nextcloud-Integration/docs/existing-nextcloud-adoption.md

Existing Nextcloud Adoption Plan

This doc covers the early rollout path for adopting an already-running Nextcloud instance into the NuQloud/Qortal stack.

Goal

We want a repeatable path that works for:

1. Existing host/VM Nextcloud installs
2. Existing Docker-based Nextcloud installs
3. Mixed environments where Nextcloud is host-native and sidecars run in Docker

Immediate Approach

Start with discovery before applying any integration changes.

Run:

./scripts/analyze-existing-nextcloud-instance.sh --text

Or save a machine-readable report:

./scripts/analyze-existing-nextcloud-instance.sh --json --output-file ./existing-nextcloud-analysis.json

The analyzer inventories:

• host services (apache2, nginx, caddy, docker, DB services)
• detected occ path and basic Nextcloud status
• DB type/host, overwrite.cli.url, trusted domain, data path
• enabled apps relevant to NuQloud rollout
• reachable Docker daemon + current Qortal/Nextcloud-related containers
• a first-pass topology recommendation

Common Topology: VM Nextcloud + Docker Sidecars

The first existing-instance target we should optimize for is:

• host-installed Nextcloud (occ on the VM)
• Apache + host DB/Redis
• Docker available for sidecars
• some Nextcloud adjuncts already present, such as:
  • notify_push
  • richdocuments
  • spreed
  • Collabora / Talk recording / TURN running outside the repo stack

For this topology, the right adoption goal is usually:

• keep the existing Nextcloud runtime intact
• avoid replacing working Talk/Office pieces on day one
• add NuQloud components around the existing install:
  • broker
  • broker DB
  • external-auth
  • optional qortal node
• then wire the host Nextcloud apps/config to those services

This is the best first candidate for a real host-nextcloud-hybrid apply path.

Current Reusable Script Pieces

We already have good building blocks:

• scripts/topology/discover-cloud-topology.sh
  • basic runtime/topology detection
• scripts/topology/apply-topology-profile.sh
  • currently supports:
    • repo-devprod-bootstrap
    • host-nextcloud-hybrid (now delegates to the host installer)
• scripts/install-host-nextcloud-hybrid.sh
  • bootstraps the host-hybrid broker/app wiring from an analyzed Nextcloud host
• scripts/update-host-nextcloud-hybrid.sh
  • refreshes bundled contexts and reapplies the host-hybrid installer
• scripts/restart-host-nextcloud-hybrid.sh
  • recreates the active host-hybrid sidecar services
• scripts/stop-host-nextcloud-hybrid.sh
  • stops the active host-hybrid sidecar services without removing volumes
• scripts/nextcloud-vm-install.sh
  • host/VM-oriented installer for existing Nextcloud outside the repo Docker stack
• scripts/finish-initial-setup.sh
  • bundled external-auth registration
  • node API key generation/sync
  • OIDC + app enablement
• scripts/ensure-*.sh
  • URL config
  • service auth
  • Talk config
  • CustomPWA push config
  • qortal integration runtime config

Target Rollout Modes

1. Full NuQloud Sidecar Stack on Existing Nextcloud

Recommended when the host already runs Nextcloud but can also run Docker sidecars.

Expected shape:

• Nextcloud remains where it is
• Docker sidecars provide:
  • broker
  • broker DB
  • external-auth
  • optional qortal node
  • optional collabora
  • optional Talk HPB / TURN / recording

This is the most likely first production adoption path.

2. Repo Devprod Stack

Recommended only when the whole cloud is intended to be managed by this repo’s compose stack.

This is already the best-supported path today.

3. App-Only / Manual External Services

For environments where Docker sidecars are not available or not desired.

This is the hardest path to automate fully and should probably remain an advanced/manual topology.

Proposed Next Build Step

The host-adoption flow now has the main entrypoints in place:

1. Discovery/preflight
   • now started by scripts/analyze-existing-nextcloud-instance.sh
2. Apply/adopt
   • scripts/install-host-nextcloud-hybrid.sh --occ-path <path>
3. Lifecycle
   • scripts/update-host-nextcloud-hybrid.sh
   • scripts/restart-host-nextcloud-hybrid.sh
   • scripts/stop-host-nextcloud-hybrid.sh

The first automated apply target should assume the common VM topology above and focus on sidecar adoption, not full replacement of the existing host install.

What the Future Host-Adoption Script Should Decide

After analyzing the target environment, the apply step should decide:

• Is Nextcloud host-native or containerized?
• Which web stack is present (apache2, nginx, caddy)?
• Which DB is in use?
• Is Docker usable for sidecars?
• Is an existing reverse proxy already in place?
• Which NuQloud modules should be enabled?
  • external-auth
  • broker
  • office
  • talk
  • turn
  • janus
  • recording
  • custom_pwa
  • qortal node

Why This Matters for App Store Readiness

The Nextcloud app-store package can eventually ship the app itself, but the full NuQloud experience still depends on a reliable environment adapter.

So the near-term app-store work should be paired with:

• app-store-like install testing (scripts/setup-appstore-mimic.sh)
• host-environment discovery
• a stable adoption workflow for existing Nextcloud installs

Without that, “install from app store” will only solve the app copy/enable step, not the full stack integration.