# Script Catalog

Use this reference when selecting repo scripts for NuQloud/Qortal Nextcloud Integration lifecycle work.

## Core Install And Runtime

- `scripts/install-production-docker.sh`
  - Primary Docker/devprod installer.
  - Use `--mode nossl` for shared/global Caddy.
  - Use `--guided` for interactive setup.
  - Use `--no-guided --with-external-auth --with-office --with-signaling` for idempotent full-profile repair.
  - Use `--accept-defaults` only for smoke testing.

- `scripts/finish-initial-setup.sh`
  - Completes app enablement, OIDC/provider setup, runtime config, maintenance repair.
  - Use after partial installer failure or after manually correcting env values.

- `recreate-devprod.sh`
  - Recreates the devprod stack from current `.env.devprod`.
  - Use `--nossl` for global Caddy deployments.
  - Supports targeted recreates such as `--qortal`, `--extauth`, and `--full`.

- `start-devprod.sh`
  - Starts an existing devprod stack from current env values.

- `stop-devprod.sh`
  - Stops `ssl`, `nossl`, or both stacks.
  - In shared/global Caddy mode, stopping bundled SSL is expected.

## Env And Ports

- `scripts/ensure-compose-project-name.sh`
  - Pins or validates stable `COMPOSE_PROJECT_NAME`.

- `scripts/ensure-env-keys.sh`
  - Ensures env file has keys from template.

- `scripts/select-host-service-ports.sh`
  - Selects free host ports for enabled service profiles.
  - Use before recreating multi-instance hosts.
  - With `--skip-when-running`, existing running services retain ports while newly enabled services are assigned free ports.

- `scripts/select-qortal-p2p-port.sh`
  - Selects a free bundled node P2P host port.

- `scripts/evaluate-set-size-defaults.sh`
  - Recommends upload/post/PHP/broker limits from host memory.

## Shared/Global Caddy

- `scripts/setup-shared-host-global-caddy.sh`
  - Orchestrates shared Caddy setup for one or more repo-based cloud instances.
  - Pass every instance that should be registered:
    `--instance-dir /path/to/cloud1 --instance-dir /path/to/cloud2`.
  - Use `--no-bootstrap` when global Caddy already exists.
  - Use `--global-caddy-dir /srv/global-caddy --container-name global_caddy`.

- `scripts/register-global-caddy-proxy.sh`
  - Writes one instance's Caddy site fragment.
  - Use directly for targeted registration.
  - Use `--upstream-host host.docker.internal` for containerized global Caddy.
  - Use `--reload --container-name global_caddy`.

- `scripts/validate-proxy-alignment.sh`
  - Verifies env/proxy expectations for external proxy mode.

- `scripts/sync-public-env-urls.sh`
  - Recomputes public URL values after domain/proxy/port changes.

## Nextcloud Configuration

- `scripts/ensure-nextcloud-url-config.sh`
  - Aligns trusted domains, trusted proxies, forwarded headers, and overwrite settings.

- `scripts/ensure-nextcloud-service-auth.sh`
  - Repairs Nextcloud service account/app password settings.

- `scripts/ensure-nextcloud-office-config.sh`
  - Enables/verifies Office/Collabora app configuration and WOPI URLs.

- `scripts/ensure-nextcloud-talk-config.sh`
  - Enables/verifies Talk signaling, TURN/STUN, and recording configuration.
  - Supports `--verify-only`.

- `scripts/ensure-custom-pwa-push-config.sh`
  - Aligns custom PWA and notify push configuration.

- `scripts/ensure-nextcloud-default-app-bundle.sh`
  - Installs/enables recommended default apps.

- `scripts/configure-nextcloud-defaults.sh`
  - Applies standard Nextcloud defaults.

- `scripts/clear-nextcloud-appdata-assets.sh`
  - Clears cached assets after app/theming changes.

- `scripts/nextcloud-occ.sh`
  - Safer helper for running `occ` through the selected env.

## Qortal Integration And Broker

- `scripts/ensure-qortal-integration-app.sh`
  - Ensures bundled app is present in the custom apps path.

- `scripts/ensure-qortal-integration-runtime-config.sh`
  - Syncs app runtime config from env.

- `scripts/verify-qortal-integration-sync.sh`
  - Verifies integration config; use `--repair` after changes.

- `scripts/ensure-qortal-core-repo.sh`
  - Ensures bundled node build context exists.

- `scripts/ensure-qortal-settings.sh`
  - Ensures bundled node settings.

- `scripts/ensure-qortal-start-args.sh`
  - Ensures bundled node start args.

- `scripts/diagnose-qortal-gateway-route.sh`
  - Diagnoses public gateway route issues.

- `scripts/ensure-broker-internal-token.sh`
  - Generates/validates broker internal API token.

- `scripts/ensure-oidc-signing-key.sh`
  - Generates/validates OIDC signing key.

- `scripts/sync-bundled-runtime-env-from-nextcloud.sh`
  - Pulls runtime values from Nextcloud into env and can restart services.

## Repair And Diagnostics

- `scripts/repair-docker-production.sh`
  - General repair wrapper for Docker production/devprod installs.

- `scripts/diagnose-nextcloud-occ-readiness.sh`
  - Diagnoses whether Nextcloud is ready for `occ` commands.

- `scripts/ensure-nextcloud-apps-writable.sh`
  - Repairs custom app writeability.

- `scripts/check-nextcloud-custom-app-compat.sh`
  - Checks app compatibility before upgrades.

- `scripts/setup-appstore-mimic.sh`
  - Prepares appstore-mimic workflow.

- `scripts/migrate-nuqloud-branding.sh`
  - Migrates branding/service user values; avoid hardcoding future branding.

## Upgrades

- `scripts/check-nextcloud-image-update.sh`
  - Checks available Nextcloud image updates.

- `upgrade-devprod-nextcloud.sh`
  - Performs Nextcloud devprod upgrade.
  - Use `--nossl --env-file .env.devprod` for shared/global Caddy instances.

## Topology And Existing Instances

- `scripts/topology/discover-cloud-topology.sh`
  - Discovers current topology.

- `scripts/topology/apply-topology-profile.sh`
  - Applies a topology profile.

- `scripts/topology/analyze-existing-nextcloud-instance.sh`
  - Analyzes existing Nextcloud instance adoption paths.

- `scripts/discover-cloud-topology.sh`, `scripts/apply-topology-profile.sh`, `scripts/analyze-existing-nextcloud-instance.sh`
  - Thin wrappers around topology scripts.

## Host-Hybrid / VM Installers

- `scripts/bootstrap-host-nextcloud-hybrid.sh`
- `scripts/install-host-nextcloud-hybrid.sh`
- `scripts/restart-host-nextcloud-hybrid.sh`
- `scripts/stop-host-nextcloud-hybrid.sh`
- `scripts/update-host-nextcloud-hybrid.sh`
- `scripts/nextcloud-vm-install.sh`

Use these only for host-hybrid or VM-style installs, not standard devprod shared-Caddy flows.

## OpenClaw Automation

- `scripts/automation/nuqloud-op`
  - Least-privilege host wrapper for a remote agent.
  - Supports `broker-health`, `invite-create`, and `provision-upsert`.

- `scripts/automation/nuqloud-op.sudoers`
  - Sudoers template. Keep the OpenClaw user out of the Docker group.

- `scripts/automation/README-agent-executor.md`
  - Installation and security notes for the wrapper.