Qortal-Nextcloud-Integration/docs/scripts-reference.md

# Script Reference

## Root Scripts

- `start-dev.sh`
  - Interactive setup for local development stack (`docker-compose.yml`).
- `start-devprod.sh`
  - Interactive setup for dev-prod stacks (`docker-compose.devprod*.yml`).
- `recreate-devprod.sh`
  - Rebuild/recreate dev-prod services after code/env changes.
  - Use `--qortal` to include `qortal_node` recreation.
  - Use `--qortal-branch <branch>` (or `--qortal=<branch>`) to rebuild Qortal from a specific upstream branch for that run.
  - Use `--full` to force no-cache rebuild of all buildable services and refresh `QORTAL_NODE_CONTEXT` from primary upstream (`https://github.com/Qortal/qortal.git`) before rebuild.
  - Use `--nc34` or `--nextcloud-image <image>` to override `NEXTCLOUD_IMAGE` for that run. `--nc33` remains a legacy fallback.
  - Use `--extauth` to force external-auth profile recreation.
  - `--extauth` alone now recreates `external_auth` without recreating `qortal_node` dependencies.
  - Re-syncs public env URLs, re-validates Nextcloud URL config, validates Talk backends, and ensures CustomPWA push/VAPID config when applicable.
- `upgrade-devprod-nextcloud.sh`
  - Safe Nextcloud Docker upgrade flow for dev-prod stacks.
  - Runs status precheck, optional backup, maintenance mode on/off, container recreate, `occ upgrade`, and post-repair tasks.
  - Detects Nextcloud DB backend from env (`mysql`/`postgres`) for backup, with optional `--db-engine` override.
  - Use `--nc34` for `nextcloud:34-apache` or `--nextcloud-image <image>` for pinned tags. `--nc33` remains available as a legacy fallback.
  - Supports `--ssl`/`--nossl`, `--backup-dir`, `--skip-backup`, `--skip-precheck`, and `--no-pull`.
- `docker-qortal-restart.sh`
  - Restarts `qortal_node` only (plus optional `--restart-external-auth`).

## `scripts/` Helpers

- `scripts/discover-cloud-topology.sh`
  - Topology detector for setup planning.
  - Outputs JSON by default, `--text` for operator-readable summary.
  - Recommends an install profile command for current environment.
- `scripts/apply-topology-profile.sh`
  - Applies a detected/setup profile.
  - `repo-devprod-bootstrap`: runs env key sync + recreate + finish setup.
  - `host-nextcloud-hybrid`: runs the host-hybrid installer and lifecycle wiring.
- `scripts/install-host-nextcloud-hybrid.sh`
  - Boots the host-hybrid broker/app stack for an existing 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/topology/*`
  - Internal grouped implementation for topology-aware setup logic.
- `scripts/nextcloud-occ.sh <env-file> <occ args...>`
  - Wrapper for running Nextcloud `occ` inside Docker app container.
- `scripts/ensure-compose-project-name.sh`
  - Pins `COMPOSE_PROJECT_NAME` in `.env.devprod` so folder renames do not attach the cloud to new named volumes.
  - Use `--project-name <stable-name>` when migrating an existing instance.
  - Use `--write-if-missing` for fresh installs/checkouts that do not have a pinned project name yet.
  - When `COMPOSE_PROJECT_NAME` is unset, the runtime scripts still fall back to the env file directory name for backward compatibility with older installs.
- `scripts/select-qortal-p2p-port.sh <env-file>`
  - Chooses an available Qortal API host port and sets P2P to API+1 and QDN to API+3.
- `scripts/ensure-qortal-settings.sh`
  - Initializes `qortal/data/settings.json` from default template when missing.
  - Ensures `autoUpdateEnabled` is set to `false` in `settings.json`.
- `scripts/ensure-qortal-start-args.sh`
  - Initializes `qortal/data/start-arguments.txt` with auto-sized JVM args when missing.
  - Auto-managed files are refreshed on restart so the heap follows host RAM.
  - Optional argument: `<env-file>` to override sizing with `QORTAL_JVM_MEMORY_ARGS`.
- `scripts/ensure-broker-internal-token.sh <env-file>`
  - Ensures `BROKER_INTERNAL_API_TOKEN` exists (auto-generates when missing).
  - Sets `BROKER_CORS_ALLOWED_ORIGINS` from `NEXTCLOUD_PUBLIC_URL` when empty.
- `scripts/ensure-oidc-signing-key.sh <env-file>`
  - Ensures the broker has a stable OIDC signing key.
  - Validates existing `OIDC_PRIVATE_KEY_PEM` or `OIDC_PRIVATE_KEY_PEM_B64`.
  - Generates `OIDC_PRIVATE_KEY_PEM_B64` when no stable key is configured.
- `scripts/evaluate-set-size-defaults.sh`
  - Evaluates host RAM and recommends env-backed upload/publish size defaults.
  - Can optionally write `BROKER_REQUEST_BODY_LIMIT`, `NEXTCLOUD_PHP_UPLOAD_MAX_FILESIZE`, `NEXTCLOUD_PHP_POST_MAX_SIZE`, `NEXTCLOUD_PHP_MEMORY_LIMIT`, and blank `QORTAL_FILES_PUBLISH_MAX_SIZE`.
  - Keeps Nextcloud PHP upload/post capacity decoupled from QDN publish limits; upload/post defaults are 5G.
  - Targets the repo's Apache-based Nextcloud image; does not tune PHP-FPM `pool.d`.
- `scripts/ensure-nextcloud-apps-writable.sh`
  - Ensures `/var/www/html/apps` and `/var/www/html/custom_apps` are writable by Nextcloud web user.
  - Called automatically by install/recreate/finish/start-devprod flows.
- `scripts/ensure-nextcloud-url-config.sh`
  - Aligns Nextcloud URL/proxy config with env and runtime topology.
  - Sets `trusted_domains`, `trusted_proxies`, `forwarded_for_headers`, and `overwrite*` values.
  - Detects host->container gateway proxy IP for no-SSL external reverse-proxy layouts.
- `scripts/register-global-caddy-proxy.sh`
  - Writes one cloud's site fragment into a shared/global Caddy config directory.
  - Supports containerized shared Caddy via `host.docker.internal`.
  - Publishes optional Qortal gateway proxy blocks when `QORTAL_PUBLIC_GATEWAY_URL` (or alias) is set.
- `scripts/validate-proxy-alignment.sh`
  - Validates Apache `remoteip`, Nextcloud trusted proxy headers, and no-SSL proxy expectations.
  - Uses `EXTERNAL_PROXY_MODE` to distinguish bundled SSL, manual external proxy, and shared/global Caddy expectations.
- `scripts/ensure-nextcloud-talk-config.sh`
  - Ensures and verifies Nextcloud Talk HPB/STUN/TURN/recording config from env values.
  - Used to catch cases where env is correct but Talk backends were not actually registered inside the cloud.
- `scripts/ensure-custom-pwa-push-config.sh`
  - Ensures CustomPWA VAPID env values exist, auto-generates missing keypairs, enables/install `custom_pwa` when configured, and syncs push settings into Nextcloud app config.
- `scripts/setup-shared-host-global-caddy.sh`
  - Multi-instance helper for switching repo-based clouds into no-SSL shared-Caddy mode on one host.
  - Updates bind hosts and `PUBLIC_HTTPS_PORT`, recreates no-SSL stacks, registers each cloud in shared Caddy, syncs Nextcloud proxy config, and validates Talk backend wiring.
- `scripts/nextcloud-vm-install.sh`
  - VM/non-container oriented installation helper.
- `scripts/analyze-existing-nextcloud-instance.sh`
  - Read-only host/environment analyzer for planning adoption of an existing Nextcloud installation into the NuQloud/Qortal stack.
- `scripts/finish-initial-setup.sh`
  - Finalizes first-run OIDC/app wiring and syncs identity-provider runtime plus billing/CHD values into `qortal_integration`.
  - Enables bundled custom apps including `nuqloud_scrum`.
  - Supports rebrand env aliases with precedence: `NUQLOUD_*` → `SOVEREIGN_*` → `SC_*` for CHD/billing-related keys.
- `scripts/ensure-qortal-integration-runtime-config.sh`
  - Syncs env-backed broker, External Auth, Qortal node, gateway, and identity-provider settings into `qortal_integration`.
  - Also syncs broker OIDC email-requirement policy through the internal broker token.
- `scripts/migrate-nuqloud-branding.sh`
  - One-time migration helper for existing pre-NuQloud dev clouds.
  - Backs up env, seeds missing `NUQLOUD_*` aliases from `SOVEREIGN_*`/`SC_*`, and can optionally switch `NEXTCLOUD_SERVICE_USER` to `nuqloud_oidc_service`.
  - Default behavior keeps existing service user (legacy `sovereign_oidc_service` remains valid).
  - Can run finish/auth repair steps to apply settings and verify broker service auth.
- `scripts/install-production-docker.sh`
  - Production-oriented Docker installer baseline.
  - Fresh env creation now pins `COMPOSE_PROJECT_NAME` automatically so instance identity is stable across folder renames.
  - Ensures bundled `QORTAL_NODE_CONTEXT` is cloned from primary upstream (`https://github.com/Qortal/qortal.git`).
  - For direct repo refresh/branch pinning, use `scripts/ensure-qortal-core-repo.sh --refresh [--branch <name>]`.
  - `--one-click` runs non-interactive auto-configuration, starts services, and auto-runs first-run finish steps.
  - Feature flags: `--with-office`, `--with-signaling` (auto-enables talk + turn + janus + recording), `--with-talk-signaling` (Talk HPB profile only).
  - Recording override flags: `--with-recording`, `--without-recording`.
  - Domain inputs: `--nextcloud-domain`, `--broker-domain`, `--office-domain`, `--signaling-domain`.
  - Guided mode prompts for Nextcloud image selection (`nextcloud:34-apache` default, `nextcloud:33-apache` fallback, or custom tag with warning).
- `scripts/setup-appstore-mimic.sh`
  - Switches env to isolated `NEXTCLOUD_CUSTOM_APPS_PATH` and seeds packaged-style app copies for marketplace-flow simulation.

## Recommended Baseline Flows

### Dev-prod no-SSL (external reverse proxy)
1. `./start-devprod.sh`
2. `./recreate-devprod.sh`
3. `make logs-devprod-nossl`

### Dev-prod SSL (internal Caddy)
1. `./start-devprod.sh`
2. `./recreate-devprod.sh --ssl`
3. `make logs-devprod`

### Production-oriented Docker bootstrap (new)
1. `./scripts/install-production-docker.sh --mode nossl --with-external-auth`
2. Optional media/collaboration stack: `--with-office --with-signaling`
3. Optional HPB-only variant: `--with-talk-signaling` (then add `--with-turn` / `--with-janus` as needed)
4. Validate service health and OIDC setup.
5. Move secrets from templates into managed secret store as needed.

For Talk HPB, `TALK_SIGNALING_PORT` is the host/public port and
`TALK_SIGNALING_CONTAINER_PORT` is the container listen port. Keep the
container port at `8081` unless the upstream Talk image changes.

### One-click bootstrap (non-interactive)
1. `./scripts/install-production-docker.sh --one-click --mode nossl`
2. Validate service health and broker/external-auth wiring.

### Topology-aware bootstrap (new)
1. `./scripts/discover-cloud-topology.sh --text`
2. Run recommended command from detector output, or:
3. `./scripts/apply-topology-profile.sh --profile repo-devprod-bootstrap`
4. For an existing host Nextcloud, use `./scripts/install-host-nextcloud-hybrid.sh --occ-path <path>` and then the lifecycle wrappers above.

### App Store mimic (isolated custom_apps mount)
1. `./scripts/setup-appstore-mimic.sh --env-file .env.devprod`
2. `./scripts/install-production-docker.sh --mode nossl --with-external-auth --env-file .env.devprod`
3. Validate with `occ app:list` and OIDC provider commands.

### One-time NuQloud rebrand migration (existing cloud)
1. `./scripts/migrate-nuqloud-branding.sh --env-file .env.devprod --mode nossl`
2. Optional service user migration: `./scripts/migrate-nuqloud-branding.sh --env-file .env.devprod --mode nossl --switch-service-user`