Qortal-Nextcloud-Integration/admin-readme.txt

Qortal ↔ Nextcloud Integration
Admin Script Guide

Purpose
This file is the operator-facing guide for the scripts in this repository.
It answers 4 questions for each script:

1. What does it do?
2. When should I use it?
3. What does it change?
4. What is the normal command to run?

This guide is written for repo-based Docker deployments first, because that is
the main admin workflow in this repository.

----------------------------------------------------------------------
1. Core Rules
----------------------------------------------------------------------

1. The main environment file for repo-based clouds is usually:
   .env.devprod

2. There are two main compose modes:
   - ssl
     Uses docker-compose.devprod.yml
     Bundled Caddy terminates TLS inside the cloud stack.
   - nossl
     Uses docker-compose.devprod.nossl.yml
     Intended for external reverse proxy setups, including shared/global Caddy.

3. For multiple clouds on one host with one shared Caddy:
   - use nossl mode
   - use unique host ports per cloud
   - let shared/global Caddy terminate public HTTPS

4. The main "fix everything I can automatically" script is:
   ./recreate-devprod.sh

5. The main "first-time deployment/bootstrap" script is:
   ./scripts/install-production-docker.sh

6. If something drifted after env/domain/proxy changes, the most important repair
   helpers are:
   - ./scripts/sync-public-env-urls.sh
   - ./scripts/ensure-nextcloud-url-config.sh
   - ./scripts/ensure-nextcloud-service-auth.sh --repair
   - ./scripts/ensure-nextcloud-talk-config.sh
   - ./scripts/ensure-custom-pwa-push-config.sh

7. For repo-based Docker clouds, pin a stable compose project name:
   - set COMPOSE_PROJECT_NAME in .env.devprod and keep it unchanged
   - do not let folder renames decide Docker volume identity
   - helper:
     ./scripts/ensure-compose-project-name.sh --env-file .env.devprod --project-name <stable-name>
   - if COMPOSE_PROJECT_NAME is missing, the scripts still fall back to the folder name for backward compatibility

----------------------------------------------------------------------
2. Quick Decision Guide
----------------------------------------------------------------------

If you want to start an already-configured cloud:
  ./start-devprod.sh

If you changed code, env values, domains, app config, or want a strong repair pass:
  ./recreate-devprod.sh --nossl
  or
  ./recreate-devprod.sh --ssl

If you are doing first-time setup of a repo-based Docker cloud:
  ./scripts/install-production-docker.sh --guided
  or
  ./scripts/install-production-docker.sh --one-click --mode nossl

If you want to evaluate an already-existing Nextcloud host before choosing an adoption path:
  ./scripts/analyze-existing-nextcloud-instance.sh --text

If OIDC / bundled external-auth / service-user wiring is incomplete after install:
  ./scripts/finish-initial-setup.sh --mode nossl --env-file .env.devprod

If the cloud is partially broken and needs a scripted repair pass:
  ./scripts/repair-docker-production.sh --mode nossl --env-file .env.devprod

If you changed the public domain, proxy, or shared-Caddy topology:
  ./scripts/sync-public-env-urls.sh --env-file .env.devprod --mode nossl
  ./scripts/ensure-nextcloud-url-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

If Talk HPB / STUN / TURN / recording is not actually configured inside Nextcloud:
  ./scripts/ensure-nextcloud-talk-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

If CustomPWA push is not working or VAPID keys are missing:
  ./scripts/ensure-custom-pwa-push-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

If you are running multiple clouds on one host with one shared Caddy:
  ./scripts/setup-shared-host-global-caddy.sh --global-caddy-dir /srv/global-caddy --container-name global_caddy --instance-dir /path/to/cloud1 --instance-dir /path/to/cloud2

If you only want to register one cloud into an already-existing shared Caddy:
  ./scripts/register-global-caddy-proxy.sh --env-file .env.devprod --target-dir /srv/global-caddy --upstream-host host.docker.internal --reload --container-name global_caddy

If you want to upgrade the Nextcloud image safely:
  ./upgrade-devprod-nextcloud.sh --nossl --env-file .env.devprod

----------------------------------------------------------------------
3. Root-Level Scripts
----------------------------------------------------------------------

start-dev.sh
What it does:
  Interactive helper for the local development stack using .env and docker-compose.yml.
When to use it:
  Only for the local dev stack, not for the repo-based devprod/prod-style clouds.
What it changes:
  Creates or updates .env and starts the local-oriented stack path.
Typical use:
  ./start-dev.sh

start-devprod.sh
What it does:
  Starts an existing devprod stack using values already present in .env.devprod.
When to use it:
  When the env is already configured and you only want to bring the stack up.
What it changes:
  Starts containers. It does not do the full repair/verification depth that recreate does.
Typical use:
  ./start-devprod.sh --nossl
  ./start-devprod.sh --ssl

stop-devprod.sh
What it does:
  Stops and removes devprod containers without deleting volumes.
When to use it:
  When switching modes, stopping a cloud cleanly, or clearing running containers before a rebuild.
What it changes:
  Runs docker compose down on ssl, nossl, or both stacks.
Typical use:
  ./stop-devprod.sh --all
  ./stop-devprod.sh --ssl
  ./stop-devprod.sh --nossl

recreate-devprod.sh
What it does:
  Rebuilds/recreates the devprod stack and then runs a broad repair/verification pass.
  It now also:
  - syncs public env URLs
  - validates Nextcloud URL config
  - checks broker service auth
  - enables/repairs OIDC and notify_push
  - validates Talk HPB/STUN/TURN/recording when enabled
  - ensures CustomPWA push/VAPID config when applicable
  - reasserts app bundle and maintenance repair
When to use it:
  This should be the default admin repair command after most configuration or code changes.
What it changes:
  Containers, app state, env-derived URL sync, app enables, Talk backend registrations, PWA push config, maintenance repair.
Typical use:
  ./recreate-devprod.sh --nossl
  ./recreate-devprod.sh --ssl
  ./recreate-devprod.sh --nossl --qortal
  ./recreate-devprod.sh --nossl --extauth
  ./recreate-devprod.sh --nossl --full

upgrade-devprod-nextcloud.sh
What it does:
  Safely upgrades the Nextcloud app and cron containers to a new Docker image.
When to use it:
  When moving to a new Nextcloud image tag.
What it changes:
  Pulls image, optional backup, maintenance mode, recreate, occ upgrade, post-repair.
Typical use:
  ./upgrade-devprod-nextcloud.sh --nossl --env-file .env.devprod
  ./upgrade-devprod-nextcloud.sh --nossl --nextcloud-image nextcloud:33.0.2-apache

docker-qortal-restart.sh
What it does:
  Restarts qortal_node only, with optional external_auth restart.
When to use it:
  When you do not want a full cloud recreate and only need to bounce Qortal Core.
What it changes:
  Restarts qortal_node and optionally external_auth.
Typical use:
  ./docker-qortal-restart.sh --nossl
  ./docker-qortal-restart.sh --nossl --restart-external-auth

----------------------------------------------------------------------
4. Main Bootstrap / Repair Scripts
----------------------------------------------------------------------

scripts/install-production-docker.sh
What it does:
  Main guided or automatic installer for repo-based Docker clouds.
  It writes env values, starts services, and performs first-run fixups.
  It now also shares the stronger final validation path:
  - URL re-sync
  - URL config verification
  - Talk verification
  - CustomPWA push/VAPID verification
When to use it:
  First-time cloud setup.
What it changes:
  Env, compose profiles, container state, app enablement, OIDC config, default bundle, Talk config, CustomPWA config.
Typical use:
  ./scripts/install-production-docker.sh --guided
  ./scripts/install-production-docker.sh --one-click --mode nossl
  ./scripts/install-production-docker.sh --mode nossl --with-external-auth --with-office --with-signaling

scripts/finish-initial-setup.sh
What it does:
  Finalizes first-run bundled-service setup after the cloud is up.
  Handles:
  - external-auth registration
  - node API key generation
  - OIDC enable/provider config
  - notify_push enablement
  - qortal_integration billing/CHD env sync
  - CustomPWA VAPID/env sync
When to use it:
  When initial install did not fully finish, or when bundled auth/runtime values need a resync.
What it changes:
  Env, external_auth registration state, Nextcloud app config, some runtime service wiring.
Typical use:
  ./scripts/finish-initial-setup.sh --mode nossl --env-file .env.devprod

scripts/repair-docker-production.sh
What it does:
  Repair pass for partially configured Docker production-style deployments.
When to use it:
  When install/recreate left the cloud in a half-working state and you want a structured repair attempt.
What it changes:
  Re-runs URL repair, service auth repair, finish setup, core maintenance fixes, optional SQLite conversion.
Typical use:
  ./scripts/repair-docker-production.sh --mode nossl --env-file .env.devprod

scripts/nextcloud-vm-install.sh
What it does:
  Installer path for VM or non-container Nextcloud environments.
When to use it:
  Only when the Nextcloud app is being installed into a host/VM Nextcloud instead of the repo Docker stack.
What it changes:
  Host-side Nextcloud OCC state and app configuration.
Typical use:
  sudo ./scripts/nextcloud-vm-install.sh

scripts/analyze-existing-nextcloud-instance.sh
What it does:
  Read-only environment analyzer for existing Nextcloud installations.
  It inventories host services, Docker availability, detected Nextcloud OCC path,
  DB/web-stack hints, enabled apps of interest, and current Qortal/Nextcloud-related containers.
When to use it:
  Before trying to adapt an arbitrary existing Nextcloud instance into the NuQloud/Qortal stack.
What it changes:
  Nothing. It is discovery-only.
Typical use:
  ./scripts/analyze-existing-nextcloud-instance.sh --text
  ./scripts/analyze-existing-nextcloud-instance.sh --json --output-file ./existing-nextcloud-analysis.json

scripts/migrate-nuqloud-branding.sh
What it does:
  Migrates legacy Sovereign/SC env naming to NuQloud naming.
When to use it:
  Existing older clouds that were set up before the NuQloud rename.
What it changes:
  Env aliases, optional service username, optional runtime sync/repair.
Typical use:
  ./scripts/migrate-nuqloud-branding.sh --env-file .env.devprod --mode nossl

scripts/setup-appstore-mimic.sh
What it does:
  Builds an isolated custom_apps path to mimic marketplace/app-store style installation behavior.
When to use it:
  Testing packaging/install/update behavior without changing the source-tree mounted app layout.
What it changes:
  NEXTCLOUD_CUSTOM_APPS_PATH and seeded app copies in the alternate path.
Typical use:
  ./scripts/setup-appstore-mimic.sh --env-file .env.devprod

----------------------------------------------------------------------
5. Shared Host / Shared Caddy Scripts
----------------------------------------------------------------------

scripts/setup-shared-host-global-caddy.sh
What it does:
  Converts one or more repo-based clouds on the same host into a shared/global Caddy layout.
  It:
  - normalizes bind hosts for containerized shared Caddy
  - normalizes PUBLIC_HTTPS_PORT
  - stops bundled SSL Caddy per instance
  - recreates each cloud in nossl mode
  - registers each cloud into shared Caddy
  - runs Nextcloud URL config sync
  - validates Talk config
When to use it:
  When you want multiple clouds on one host behind one shared Caddy.
What it changes:
  Each selected cloud's env, container mode, Caddy site fragments, and Nextcloud URL state.
Typical use:
  ./scripts/setup-shared-host-global-caddy.sh --global-caddy-dir /srv/global-caddy --container-name global_caddy --instance-dir /srv/clouds/cloud1 --instance-dir /srv/clouds/cloud2

scripts/register-global-caddy-proxy.sh
What it does:
  Writes one cloud's site fragment into the shared Caddy config directory.
When to use it:
  When adding one cloud to an existing shared Caddy, or after changing a cloud's public domains.
What it changes:
  Writes or updates a .caddy site fragment and can reload the shared proxy.
Typical use:
  ./scripts/register-global-caddy-proxy.sh --env-file .env.devprod --target-dir /srv/global-caddy --upstream-host host.docker.internal --reload --container-name global_caddy

Important note:
  If you change NEXTCLOUD_DOMAIN for a cloud and rely on the default generated site id,
  the old site fragment does not automatically disappear. Remove the old file from:
  /srv/global-caddy/sites/
  if the old hostname should no longer be served.

----------------------------------------------------------------------
6. Validation / Repair Helpers
----------------------------------------------------------------------

scripts/sync-public-env-urls.sh
What it does:
  Recomputes env-derived public URLs and related values from current domains and HTTPS port.
When to use it:
  After domain changes, proxy changes, SSL/nossl transitions, or legacy port cleanup such as removing :444.
What it changes:
  Env file values such as:
  - NEXTCLOUD_PUBLIC_URL
  - OIDC_ISSUER
  - OIDC_REDIRECT_URI_ALLOWLIST
  - COLLABORA_PUBLIC_URL
  - TALK_SIGNALING_PUBLIC_URL
  - TALK_TURN_SERVER
  - TALK_STUN_SERVER
Typical use:
  ./scripts/sync-public-env-urls.sh --env-file .env.devprod --mode nossl

scripts/ensure-nextcloud-url-config.sh
What it does:
  Syncs Nextcloud system URL/proxy config from env/runtime topology.
When to use it:
  After any public domain, reverse proxy, or shared-Caddy change.
What it changes:
  trusted_domains, trusted_proxies, forwarded_for_headers, overwrite.cli.url, overwritehost, overwriteprotocol.
Typical use:
  ./scripts/ensure-nextcloud-url-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

scripts/ensure-nextcloud-service-auth.sh
What it does:
  Verifies broker to Nextcloud OCS service authentication, optionally repairing it.
When to use it:
  If broker-related service auth is failing, or after env/user drift around NEXTCLOUD_SERVICE_USER.
What it changes:
  Can repair the service-auth relationship if called with --repair.
Typical use:
  ./scripts/ensure-nextcloud-service-auth.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod --repair

scripts/ensure-nextcloud-talk-config.sh
What it does:
  Ensures and verifies Nextcloud Talk HPB/STUN/TURN/recording config from env.
When to use it:
  When Talk env values look right but the backends are not actually configured in Nextcloud.
What it changes:
  Talk backend registrations inside Nextcloud.
Typical use:
  ./scripts/ensure-nextcloud-talk-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod
  ./scripts/ensure-nextcloud-talk-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod --verify-only

scripts/ensure-custom-pwa-push-config.sh
What it does:
  Ensures CustomPWA VAPID/push setup is real, not just present in your memory.
  It will:
  - generate missing VAPID subject
  - generate missing VAPID keypair
  - install/enable custom_pwa when configured
  - sync app config values
  - verify the final values exist in Nextcloud
When to use it:
  Whenever PWA push is failing, VAPID keys are missing, or you want to repair push setup without a full recreate.
What it changes:
  Env file and custom_pwa app config.
Typical use:
  ./scripts/ensure-custom-pwa-push-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod
  ./scripts/ensure-custom-pwa-push-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod --verify-only

scripts/ensure-nextcloud-default-app-bundle.sh
What it does:
  Ensures the default optional Nextcloud apps are installed/enabled and the default dashboard/apps order is applied.
When to use it:
  After app drift, after upgrades, or when expected default apps are missing.
What it changes:
  App installs, app enables, default bundle configuration, and db:add-missing-indices unless skipped.
Typical use:
  ./scripts/ensure-nextcloud-default-app-bundle.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

scripts/configure-nextcloud-defaults.sh
What it does:
  Configures onboarding/default behavior, including an empty skeleton directory flow.
When to use it:
  When fixing default user experience, skeleton files, or integrity around customized defaults.
What it changes:
  Nextcloud default onboarding/skeleton behavior and optionally verifies core integrity.
Typical use:
  ./scripts/configure-nextcloud-defaults.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

scripts/clear-nextcloud-appdata-assets.sh
What it does:
  Clears appdata-generated frontend asset caches.
When to use it:
  When the UI still looks stale after app updates, app toggles, CSS/JS changes, or cache weirdness.
What it changes:
  Removes cached generated assets from appdata.
Typical use:
  ./scripts/clear-nextcloud-appdata-assets.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod

scripts/verify-qortal-integration-sync.sh
What it does:
  Verifies that the qortal_integration source app and mounted custom_apps copy are in sync.
When to use it:
  When an app copy may be stale or the mounted app path may not match source.
What it changes:
  With --repair, it refreshes the mounted app copy and OCC state.
Typical use:
  ./scripts/verify-qortal-integration-sync.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod --repair

scripts/sync-bundled-runtime-env-from-nextcloud.sh
What it does:
  Pulls bundled runtime credentials back out of qortal_integration app config and writes them into the env file.
When to use it:
  If Nextcloud app config became the source of truth and the env should be brought back in sync.
What it changes:
  Env keys and optionally restarts broker/external_auth.
Typical use:
  ./scripts/sync-bundled-runtime-env-from-nextcloud.sh --mode nossl --env-file .env.devprod --restart-services

scripts/check-nextcloud-image-update.sh
What it does:
  Queries Docker Hub and tells you whether a newer published Nextcloud tag exists for the configured track.
When to use it:
  Before upgrades, or as an informational check during recreate flows.
What it changes:
  Nothing. Read-only check.
Typical use:
  ./scripts/check-nextcloud-image-update.sh --env-file .env.devprod

----------------------------------------------------------------------
7. App / Source / Content Preparation Helpers
----------------------------------------------------------------------

scripts/ensure-env-keys.sh
What it does:
  Appends missing env keys from a template into an existing env file without overwriting existing values.
When to use it:
  After repo updates that introduced new env keys.
What it changes:
  Adds missing KEY=VALUE lines into the target env file.
Typical use:
  ./scripts/ensure-env-keys.sh --env-file .env.devprod --template-file .env.example

scripts/ensure-broker-internal-token.sh
What it does:
  Ensures BROKER_INTERNAL_API_TOKEN exists and seeds BROKER_CORS_ALLOWED_ORIGINS when empty.
When to use it:
  If broker internal auth token is missing or CORS origins were not initialized.
What it changes:
  Env values in-place.
Typical use:
  ./scripts/ensure-broker-internal-token.sh .env.devprod

scripts/ensure-nextcloud-apps-writable.sh
What it does:
  Ensures core writable Nextcloud directories are writable by the web user inside the app container.
When to use it:
  If app installs/updates fail due to permissions.
What it changes:
  Ownership/permissions inside the Nextcloud container paths.
Typical use:
  ./scripts/ensure-nextcloud-apps-writable.sh --mode nossl --env-file .env.devprod

scripts/ensure-qortal-core-repo.sh
What it does:
  Clones or refreshes the bundled Qortal Core source tree used by qortal_node builds.
When to use it:
  If the Qortal source repo is missing, stale, or you want to refresh/pin a branch.
What it changes:
  The repo at QORTAL_NODE_CONTEXT or default ../qortal.
Typical use:
  ./scripts/ensure-qortal-core-repo.sh --refresh
  ./scripts/ensure-qortal-core-repo.sh --refresh --branch main

scripts/ensure-qortal-integration-app.sh
What it does:
  Syncs qortal_integration and optional bundled apps into the mounted custom_apps path.
When to use it:
  If mounted custom app copies are missing or stale.
What it changes:
  Files in NEXTCLOUD_CUSTOM_APPS_PATH.
Typical use:
  NEXTCLOUD_CUSTOM_APPS_PATH=./nextcloud/custom_apps ./scripts/ensure-qortal-integration-app.sh

scripts/ensure-user-oidc-app.sh
What it does:
  Ensures the user_oidc app exists in the mounted custom_apps path, either from a local source or by download.
When to use it:
  When OIDC bootstrap requires user_oidc but it is missing from the mounted app path.
What it changes:
  Files in NEXTCLOUD_CUSTOM_APPS_PATH/user_oidc.
Typical use:
  NEXTCLOUD_CUSTOM_APPS_PATH=./nextcloud/custom_apps ./scripts/ensure-user-oidc-app.sh

scripts/ensure-qortal-settings.sh
What it does:
  Creates qortal/data/settings.json from template when missing and forces autoUpdateEnabled=false.
When to use it:
  Before first qortal_node start, or if Qortal settings were lost.
What it changes:
  qortal/data/settings.json
Typical use:
  ./scripts/ensure-qortal-settings.sh

scripts/ensure-qortal-start-args.sh
What it does:
  Creates or refreshes qortal/data/start-arguments.txt with auto-sized JVM args.
When to use it:
  Before first qortal_node start or when auto-managed sizing should follow host RAM.
What it changes:
  qortal/data/start-arguments.txt
Typical use:
  ./scripts/ensure-qortal-start-args.sh .env.devprod

scripts/select-host-service-ports.sh
What it does:
  Picks free host ports for enabled services and writes them into the env file.
When to use it:
  Before first run, when adding profiles, or when moving to shared-host multi-cloud layouts.
What it changes:
  Host port env values in-place.
Typical use:
  ./scripts/select-host-service-ports.sh --env-file .env.devprod --mode nossl

scripts/select-qortal-p2p-port.sh
What it does:
  Chooses a coherent Qortal API/P2P/QDN port set and writes it to the env file.
When to use it:
  If Qortal ports are missing or conflicting.
What it changes:
  Qortal host port env values.
Typical use:
  ./scripts/select-qortal-p2p-port.sh .env.devprod

----------------------------------------------------------------------
8. Topology / Discovery Helpers
----------------------------------------------------------------------

scripts/discover-cloud-topology.sh
What it does:
  Detects the runtime shape and recommends an install/bootstrap profile.
When to use it:
  When deciding which setup path applies to a machine or deployment target.
What it changes:
  Nothing. Discovery only.
Typical use:
  ./scripts/discover-cloud-topology.sh --text

scripts/apply-topology-profile.sh
What it does:
  Applies a discovered setup profile.
When to use it:
  When you want to follow the topology detector’s recommended scripted path.
What it changes:
  Depends on chosen profile. Can trigger bootstrap/recreate/finish flows.
Typical use:
  ./scripts/apply-topology-profile.sh --profile repo-devprod-bootstrap

----------------------------------------------------------------------
9. Convenience / OCC Helper
----------------------------------------------------------------------

scripts/nextcloud-occ.sh
What it does:
  Wrapper for running occ inside the Docker app container as www-data.
When to use it:
  When you want a short command for ad hoc OCC work.
What it changes:
  Whatever the OCC command changes.
Typical use:
  ./scripts/nextcloud-occ.sh .env.devprod status
  COMPOSE_FILE=docker-compose.devprod.nossl.yml ./scripts/nextcloud-occ.sh .env.devprod app:list

----------------------------------------------------------------------
10. Recommended Admin Workflows
----------------------------------------------------------------------

Normal change after editing env or code:
  1. ./recreate-devprod.sh --nossl
  2. If any warning remains, run the printed helper commands directly.

Fix public domain, proxy, or shared-Caddy drift:
  1. Update .env.devprod
  2. ./scripts/sync-public-env-urls.sh --env-file .env.devprod --mode nossl
  3. ./scripts/ensure-nextcloud-url-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod
  4. ./recreate-devprod.sh --nossl

Fix Talk drift:
  1. ./scripts/ensure-nextcloud-talk-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod
  2. If needed, ./recreate-devprod.sh --nossl

Fix PWA push drift:
  1. ./scripts/ensure-custom-pwa-push-config.sh --compose-file docker-compose.devprod.nossl.yml --env-file .env.devprod
  2. If needed, ./recreate-devprod.sh --nossl

First-time repo cloud:
  1. ./scripts/install-production-docker.sh --guided
  2. If anything partially fails, run:
     ./scripts/finish-initial-setup.sh --mode nossl --env-file .env.devprod
  3. Then run:
     ./recreate-devprod.sh --nossl

Move multiple clouds behind one shared Caddy:
  1. Prepare unique host ports in each cloud env
  2. Run:
     ./scripts/setup-shared-host-global-caddy.sh --global-caddy-dir /srv/global-caddy --container-name global_caddy --instance-dir /path/to/cloud1 --instance-dir /path/to/cloud2

Upgrade Nextcloud safely:
  1. ./scripts/check-nextcloud-image-update.sh --env-file .env.devprod
  2. ./upgrade-devprod-nextcloud.sh --nossl --env-file .env.devprod --nextcloud-image nextcloud:<tag>
  3. ./recreate-devprod.sh --nossl

----------------------------------------------------------------------
11. Important Warnings
----------------------------------------------------------------------

1. Shared/global Caddy mode is for nossl stacks.
   Do not leave a bundled per-cloud SSL Caddy running on public ports if a shared
   Caddy is supposed to own 80/443.

2. If a cloud used to run on a nonstandard public HTTPS port like :444, normalize:
   PUBLIC_HTTPS_PORT=443
   then run:
   - sync-public-env-urls.sh
   - ensure-nextcloud-url-config.sh

3. If you change a cloud's public domain and use shared Caddy, remove the old
   site fragment from /srv/global-caddy/sites/ if it should no longer be active.

4. If recreate says OCC is not ready, do not assume the stack is healthy just
   because containers are running. Follow the printed manual commands.

5. If Talk or CustomPWA env values are correct but the app still is not working,
   run the dedicated ensure script. Env correctness alone does not guarantee
   Nextcloud internal config was actually applied.

----------------------------------------------------------------------
12. Related Docs
----------------------------------------------------------------------

General script reference:
  docs/scripts-reference.md

Shared/global Caddy:
  docs/global-caddy-proxy.md

OIDC:
  docs/nextcloud-oidc-setup.md

Testing:
  docs/testing-guide.md

NuQloud blueprint and product context:
  docs/nuqloud-blueprint.md

End of file.