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

---
name: nuqloud-deployment-ops
description: 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](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:

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

For non-interactive/full profile repair or install:

```bash
./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:

```bash
./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:

```bash
--upstream-host host.docker.internal
```

## Profiles

Expected full profile line:

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

Verify after installer runs:

```bash
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:

```bash
./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:

```bash
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:

```bash
./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:

```bash
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:

```caddyfile
import /etc/caddy/sites/*.caddy
```

## Verification

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

```bash
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:

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

Finish incomplete app/OIDC/runtime setup:

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

Recreate current stack:

```bash
./recreate-devprod.sh --nossl
```

Partial profile/Caddy repair:

```bash
./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:

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

Upgrade:

```bash
./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:

```bash
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.