# 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:

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

Or save a machine-readable report:

```bash
./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.