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