Qortal-Nextcloud-Integration/docs/devprod-ssl.md

Dev-Production SSL Stack

This stack mirrors the local dev environment, but adds HTTPS via Caddy.

Files

• docker-compose.devprod.yml
• docker-compose.devprod.nossl.yml
• .env.devprod.example
• deploy/Caddyfile.devprod

Setup

1. Copy env and edit:

cp .env.devprod.example .env.devprod

Or run the helper script:

./start-devprod.sh

The script can also set the Nextcloud trusted domain for you. If you skip it, run:

make trust-domain-devprod-nossl domain=cloud.example.com

The helper scripts also ensure:

• BROKER_INTERNAL_API_TOKEN is present (auto-generated if missing)
• BROKER_CORS_ALLOWED_ORIGINS defaults to NEXTCLOUD_PUBLIC_URL when empty

2. Set domains:

NEXTCLOUD_DOMAIN=cloud.example.com
BROKER_DOMAIN=qortalbroker.example.com

3. Start the stack:

make up-devprod

4. Install the OIDC app (if needed):

make install-oidc-devprod

5. Configure user_oidc provider (example):

make occ-devprod cmd="user_oidc:provider qortal -c nextcloud-local -s dev-secret -d https://qortalbroker.example.com/.well-known/openid-configuration --scope='openid profile email' --mapping-uid=sub --mapping-display-name=name --mapping-email=email"

6. Rebuild/recreate after env changes:

./recreate-devprod.sh

This script now also disables/enables the qortal_integration app to refresh assets.

7. Upgrade Nextcloud image safely (maintenance mode + backup + migrations):

./upgrade-devprod-nextcloud.sh --nc34

For pinned patch versions:

./upgrade-devprod-nextcloud.sh --nextcloud-image nextcloud:34.0.0-apache

Notes

• For public domains, leave CADDY_TLS empty so Caddy uses Let's Encrypt.
• For local testing, set:

CADDY_TLS=tls internal

• To avoid port conflicts (e.g. local Caddy already on 443), override:

CADDY_HTTP_PORT=8081
CADDY_HTTPS_PORT=8443

• For local TLS, you must trust the Caddy local CA cert.

• If you have an external proxy handling TLS, use the no-SSL stack:

make up-devprod-nossl

Then proxy to:

• Nextcloud: http://127.0.0.1:${DEVPROD_HTTP_PORT}
• Broker: http://127.0.0.1:${DEVPROD_BROKER_PORT}
• Optional Qortal node API/gateway: http://127.0.0.1:${QORTAL_NODE_API_HOST_PORT} and internal gateway on 8080 via template configs in deploy/templates/proxy/

After changing proxy topology, align Nextcloud URL/proxy config:

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

This updates:

• trusted_domains
• trusted_proxies (including detected host->container gateway proxy IP)
• forwarded_for_headers (default HTTP_X_FORWARDED_FOR)
• overwrite.cli.url, overwritehost, overwriteprotocol

Verification:

docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod \
  exec -T --user www-data app php occ config:system:get trusted_proxies
docker compose -f docker-compose.devprod.nossl.yml --env-file .env.devprod \
  exec -T --user www-data app php occ config:system:get forwarded_for_headers

For Caddy, forwarded headers are passed by default. Only add header_up overrides when needed, and only inside a reverse_proxy { ... } block. If Caddy reports unrecognized directive: header_up, the directive is outside reverse_proxy scope.

External Auth container (optional)

To run the External Auth container alongside the stack, set the profile:

COMPOSE_PROFILES=external-auth make up-devprod-nossl

Then set:

QORTAL_EXTERNAL_AUTH_BASE_URL=http://external_auth:3191

When using the no-SSL stack, update:

PUBLIC_HTTPS_PORT=443

• If app:install user_oidc fails with a permissions error, run:

make fix-apps-perms-devprod

• If you created .env.devprod before we added optional OIDC env keys, add:

OIDC_LOGIN_LOGO_URL=
OIDC_PRIVATE_KEY_PEM=
OIDC_KEY_ID=

URL/Proxy Helpers

If you see "untrusted domain" or forwarded-header warnings, run:

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

• make trust-domain-devprod-nossl is still available for trusted-domain-only fixes.
• Broker must be reachable by both Nextcloud and browser clients.
• If user_oidc fails redirect validation, confirm NEXTCLOUD_PUBLIC_URL and OIDC_REDIRECT_URI_ALLOWLIST match your public domain exactly.