fix: surface Dokploy API errors and normalize panel URL

curl -f hid 404 bodies; strip accidental /api on DOKPLOY_URL so compose.deploy diagnostics are actionable.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/deployment/dokploy.md

@@ -104,13 +104,15 @@ Repository secrets used by workflows:
 
 | Secret | Purpose |
 |---|---|
-| `DOKPLOY_URL` | Base URL of the Dokploy panel (no trailing slash) |
+| `DOKPLOY_URL` | Panel origin **without** `/api` (e.g. `https://panel.example.com`). Do not use the OpenAPI base URL that ends in `/api` — that yields `/api/api/...` and 404s. |
 | `DOKPLOY_API_KEY` | API key from Dokploy profile → API/CLI |
-| `DOKPLOY_STAGING_COMPOSE_ID` | Staging compose id |
+| `DOKPLOY_STAGING_COMPOSE_ID` | Staging **Compose** service id (not an Application id) |
-| `DOKPLOY_PRODUCTION_COMPOSE_ID` | Production compose id |
+| `DOKPLOY_PRODUCTION_COMPOSE_ID` | Production **Compose** service id (not an Application id) |
 | `STAGING_URL` | Public origin for staging smoke (e.g. `https://staging.example.com`) |
 | `PRODUCTION_URL` | Public origin for production smoke |
 
+HTTP 404 from `compose.deploy` usually means the compose id is wrong (Application id instead of Compose) or `DOKPLOY_URL` still includes `/api`.
+
 `GITHUB_TOKEN` (automatic) publishes to GHCR with `packages:write`. No Laravel/`APP_KEY`/DB/R2/Resend secrets belong in GitHub for this pipeline.
 
 ## Workflows

scripts/deploy/dokploy-deploy.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Trigger a Dokploy Compose deploy and wait until it finishes.
 # Required env:
-#   DOKPLOY_URL          e.g. https://panel.example.com
+#   DOKPLOY_URL          e.g. https://panel.example.com (panel origin, no /api)
 #   DOKPLOY_API_KEY      x-api-key value
 #   DOKPLOY_COMPOSE_ID   target compose id
 # Optional env:
@@ -15,21 +15,53 @@ set -euo pipefail
 : "${DOKPLOY_API_KEY:?DOKPLOY_API_KEY is required}"
 : "${DOKPLOY_COMPOSE_ID:?DOKPLOY_COMPOSE_ID is required}"
 
+# Panel origin only: strip trailing slash and accidental OpenAPI /api suffix.
 DOKPLOY_URL="${DOKPLOY_URL%/}"
+DOKPLOY_URL="${DOKPLOY_URL%/api}"
+DOKPLOY_URL="${DOKPLOY_URL%/}"
+
 DEPLOY_TITLE="${DEPLOY_TITLE:-GitHub deploy}"
 DEPLOY_TIMEOUT_SEC="${DEPLOY_TIMEOUT_SEC:-900}"
 DEPLOY_POLL_SEC="${DEPLOY_POLL_SEC:-10}"
 
+echo "Dokploy API base: ${DOKPLOY_URL}/api"
+
 api() {
   local method="$1"
   local path="$2"
   shift 2
-  curl -fsS -X "$method" \
+  local url="${DOKPLOY_URL}/api${path}"
-    -H "accept: application/json" \
+  local response http_code body
-    -H "content-type: application/json" \
+
-    -H "x-api-key: ${DOKPLOY_API_KEY}" \
+  # Body then HTTP status on the last line (no -f so 4xx/5xx still return a body).
-    "${DOKPLOY_URL}/api${path}" \
+  response="$(
-    "$@"
+    curl -sS -w $'\n%{http_code}' -X "$method" \
+      -H "accept: application/json" \
+      -H "content-type: application/json" \
+      -H "x-api-key: ${DOKPLOY_API_KEY}" \
+      "$url" \
+      "$@"
+  )" || {
+    echo "Dokploy API request failed (curl transport error)." >&2
+    echo "  method: ${method}" >&2
+    echo "  url: ${url}" >&2
+    exit 1
+  }
+
+  http_code="$(printf '%s' "$response" | tail -n1)"
+  body="$(printf '%s' "$response" | sed '$d')"
+
+  if [[ ! "$http_code" =~ ^2[0-9][0-9]$ ]]; then
+    echo "Dokploy API error." >&2
+    echo "  method: ${method}" >&2
+    echo "  url: ${url}" >&2
+    echo "  status: ${http_code}" >&2
+    echo "  body:" >&2
+    printf '%s\n' "$body" >&2
+    exit 1
+  fi
+
+  printf '%s' "$body"
 }
 
 echo "Triggering Dokploy compose.deploy for ${DOKPLOY_COMPOSE_ID}..."