Qortal-Nextcloud-Integration/agent-skills/nuqloud-deployment-ops/SKILL.md

name, description

name	description
nuqloud-deployment-ops	Full lifecycle operations for NuQloud/Qortal Nextcloud Integration deployments using this repository's scripts. Use when installing new instances, repairing partial installs, configuring shared/global Caddy, selecting ports, validating proxy and Nextcloud settings, finishing setup, checking health, upgrading Nextcloud, managing profiles, or guiding an OpenClaw-style deployment agent.

NuQloud Deployment Ops

Operating Rules

• Prefer repository scripts over manual Docker or occ commands.
• Do not run Docker/Nextcloud locally unless the current machine is the target deployment host. If not on the target host, provide commands only.
• Use relative env-file arguments such as --env-file .env.devprod; avoid absolute env-file paths in user-facing commands.
• Shared/global Caddy deployments use nossl stacks. Do not start bundled SSL for those instances.
• Treat .env.devprod as source of truth. Confirm COMPOSE_PROJECT_NAME stays stable.
• Never expose secrets from .env.devprod, logs, broker tokens, OIDC secrets, or signing keys.
• For OpenClaw automation, prefer least privilege. Use scripts/automation/nuqloud-op only for its supported broker actions; full deployment still needs a deployment shell with Docker access or an explicitly approved privileged path.

References

Read references/script-catalog.md when choosing scripts, flags, or recovery commands. It maps deployment, Caddy, verification, repair, upgrade, and automation scripts.

Decision Tree

1. New single instance with bundled proxy:

   • Run ./scripts/install-production-docker.sh --mode ssl --guided --env-file .env.devprod only when this instance owns public ports 80/443.

2. New instance behind shared/global Caddy:

   • Run installer in nossl.
   • Register all instances that should be present in shared Caddy, not only the new one.
   • Validate proxy alignment and service-specific configs.

3. Existing or partial instance:

   • Re-run installer with explicit profile flags.
   • Run targeted ensure/repair scripts.
   • Recreate only through repo scripts.

4. Upgrade:

   • Check image compatibility/update first.
   • Use upgrade-devprod-nextcloud.sh.
   • Recreate and validate.

New Shared-Caddy Instance

Use this sequence on the new instance repo directory:

./scripts/install-production-docker.sh \
  --mode nossl \
  --env-file .env.devprod \
  --guided

For non-interactive/full profile repair or install:

./scripts/install-production-docker.sh \
  --mode nossl \
  --env-file .env.devprod \
  --no-guided \
  --with-external-auth \
  --with-office \
  --with-signaling

Then register every cloud that should be served by the shared proxy:

./scripts/setup-shared-host-global-caddy.sh \
  --global-caddy-dir /srv/global-caddy \
  --container-name global_caddy \
  --no-bootstrap \
  --instance-dir /path/to/existing-instance \
  --instance-dir "$PWD"

If the running global Caddy is containerized and not bootstrapped by this repo, pass:

--upstream-host host.docker.internal

Profiles

Expected full profile line:

COMPOSE_PROFILES=external-auth,office,talk,turn,janus,recording

Verify after installer runs:

grep '^COMPOSE_PROFILES=' .env.devprod

If profiles are missing, rerun installer with explicit flags. Do not manually edit profile services unless the installer cannot run.

Ports

Run port selection before recreating a multi-instance host:

./scripts/select-host-service-ports.sh \
  --env-file .env.devprod \
  --mode nossl \
  --compose-file docker-compose.devprod.nossl.yml \
  --skip-when-running

Inspect assigned profile ports:

grep -E '^(DEVPROD_HTTP_PORT|DEVPROD_BROKER_PORT|EXTERNAL_AUTH_PORT|COLLABORA_PORT|TALK_SIGNALING_PORT|TALK_TURN_PORT|TALK_RECORDING_PORT)=' .env.devprod

Global Caddy

Register one instance directly:

./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 /srv/global-caddy contains only sites/, verify that the actual Caddy config imports those fragments:

docker inspect global_caddy --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
docker exec global_caddy caddy validate --config /etc/caddy/Caddyfile
find /srv/global-caddy -maxdepth 2 -type f -print

The root Caddyfile must effectively import:

import /etc/caddy/sites/*.caddy

Verification

After install, repair, profile changes, or global Caddy changes:

docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod ps

./scripts/validate-proxy-alignment.sh \
  --compose-file docker-compose.devprod.nossl.yml \
  --env-file .env.devprod

./scripts/ensure-nextcloud-url-config.sh \
  --compose-file docker-compose.devprod.nossl.yml \
  --env-file .env.devprod

./scripts/ensure-nextcloud-office-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

./scripts/verify-qortal-integration-sync.sh \
  --compose-file docker-compose.devprod.nossl.yml \
  --env-file .env.devprod \
  --repair

Use --verify-only where supported when the user explicitly asks for read-only checks.

Repair

General repair:

./scripts/repair-docker-production.sh --mode nossl --env-file .env.devprod

Finish incomplete app/OIDC/runtime setup:

./scripts/finish-initial-setup.sh --mode nossl --env-file .env.devprod

Recreate current stack:

./recreate-devprod.sh --nossl

Partial profile/Caddy repair:

./scripts/install-production-docker.sh \
  --mode nossl \
  --env-file .env.devprod \
  --no-guided \
  --with-external-auth \
  --with-office \
  --with-signaling

./scripts/setup-shared-host-global-caddy.sh \
  --global-caddy-dir /srv/global-caddy \
  --container-name global_caddy \
  --no-bootstrap \
  --instance-dir /path/to/existing-instance \
  --instance-dir "$PWD"

Upgrade

Check before upgrading:

./scripts/check-nextcloud-image-update.sh --env-file .env.devprod
./scripts/check-nextcloud-custom-app-compat.sh --env-file .env.devprod

Upgrade:

./upgrade-devprod-nextcloud.sh --nossl --env-file .env.devprod

Then run the verification block.

OpenClaw Agent Executor

For limited broker operations on a target host, install the wrapper from scripts/automation/README-agent-executor.md. Supported actions:

sudo /usr/local/sbin/nuqloud-op broker-health
sudo /usr/local/sbin/nuqloud-op invite-create cloudOps 24
sudo /usr/local/sbin/nuqloud-op provision-upsert <qortalAddress> <email>

Do not add the OpenClaw user to the Docker group. Docker group membership is root-equivalent.

Output Style

For deployment assistance, answer with:

• Summary: concise status or changes.
• Test commands: target-host commands only.
• Required user actions: only items the user must perform.