178 lines
5.3 KiB
Markdown
178 lines
5.3 KiB
Markdown
# 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.
|