Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -136,9 +136,20 @@ set, `worker-plugin` is expected to remain idle and must not consume
|
||||
`hivegrid.plugin-invoke`.
|
||||
`worker-import` is provisioned the same way: keep it as a separate internal app,
|
||||
but leave `IMPORT_QUEUE_ENABLED` and `IMPORT_QUEUE_RUNTIME_READY` unset until
|
||||
the import, export, and scan services are wired. While idle, it must not consume
|
||||
`hivegrid.imports` or `hivegrid.exports`; once both gates are enabled, startup
|
||||
fails closed unless those services are present.
|
||||
the generic import, export, and scan services are wired. It always consumes the
|
||||
isolated `hivegrid.kwp-imports` provider queue; while the generic gates are off,
|
||||
it must not consume `hivegrid.imports` or `hivegrid.exports`. Once both gates
|
||||
are enabled, startup fails closed unless those generic services are present.
|
||||
|
||||
For the internal customer-portal closeout, `worker-import` also supports a
|
||||
strictly narrower, mutually exclusive mode: set
|
||||
`PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` while both `IMPORT_QUEUE_*` gates remain
|
||||
unset or `false`. That mode adds `hivegrid.exports` beside the always-active
|
||||
KWP queue, bootstraps only the portal and privacy GDPR export services, and
|
||||
requires the complete `STORAGE_*` S3 contract. A wrong worker group, mixed gate
|
||||
state, missing storage, or either missing GDPR service keeps
|
||||
readiness/startup fail-closed. It does not enable tenant import submission or
|
||||
the generic import/scan/export runtime.
|
||||
|
||||
| Coolify app | Required env | Public FQDN | Health port | Admin/metrics port |
|
||||
| ---------------- | ---------------------------- | ----------- | ----------- | ------------------ |
|
||||
@@ -148,7 +159,7 @@ fails closed unless those services are present.
|
||||
| `worker-webhook` | `WORKER_QUEUE_GROUP=webhook` | none | `9104` | `9204` |
|
||||
| `worker-plugin` | `WORKER_QUEUE_GROUP=plugin` | none | `9105` | `9205` |
|
||||
|
||||
These worker apps are internal services, not public web resources. Do not assign public FQDNs to them. Coolify readiness should probe `/readyz` on each app's `WORKER_HEALTH_PORT`; `/healthz` remains the lightweight liveness/manual probe. Metrics/admin endpoints, when enabled, must use the separate `WORKER_ADMIN_PORT` so they do not collide with health probes.
|
||||
These worker apps are internal services, not public web resources. Do not assign public FQDNs to them. Managed Coolify apps must use an enabled `cmd` healthcheck with `node apps/worker/dist/deploy-health.js <40-character lowercase Git SHA> <worker-group>`, where both arguments identify the immutable image and the exact `general`, `mail`, `import`, `webhook`, or `plugin` resource expected for that rollout. The command compares the requested revision with the root-owned image-baked revision and `APP_REVISION`, requires `WORKER_ENABLED=true` plus the expected `WORKER_QUEUE_GROUP`, and then probes the running worker process over loopback `/readyz`. `/healthz` remains the lightweight liveness/manual probe. Metrics/admin endpoints, when enabled, must use the separate `WORKER_ADMIN_PORT` so they do not collide with health probes.
|
||||
|
||||
Before enabling production worker processing:
|
||||
|
||||
@@ -156,17 +167,18 @@ Before enabling production worker processing:
|
||||
- configure `BULLMQ_REDIS_URL` or an approved `REDIS_URL` fallback in the runtime secret store;
|
||||
- provision all five persistent Coolify worker apps (`worker-general`, `worker-mail`, `worker-import`, `worker-webhook`, `worker-plugin`) with distinct `WORKER_QUEUE_GROUP`, `WORKER_HEALTH_PORT`, and `WORKER_ADMIN_PORT` values;
|
||||
- ensure database, mail, and browser runtime keys are present only for integrations used by that deployment;
|
||||
- keep `worker-import` idle until `IMPORT_QUEUE_ENABLED=true` and `IMPORT_QUEUE_RUNTIME_READY=true` are backed by wired import, export, and scan services;
|
||||
- keep `worker-import` idle until either the full import gates are backed by wired import/export/scan services or the mutually exclusive `PORTAL_GDPR_EXPORT_QUEUE_ENABLED=true` mode is backed by both GDPR export services and complete `STORAGE_*` configuration;
|
||||
- for production plugin runtime, set `PLUGIN_RUNTIME_PRODUCTION_ENABLED=true` only after external signoff, provide `PLUGIN_TRUSTED_PUBLIC_KEYS`, keep `PLUGIN_HOOK_FANOUT_ENABLED` and `PLUGIN_CAPABILITY_USE_ENABLED` unset or enabled on `worker-general`, and run `pnpm run verify:plugin-runtime-live` in both `worker-general` and `worker-plugin` before tenant enablement;
|
||||
- deploy enough worker capacity for expected queue volume and retry behavior;
|
||||
- confirm queue names and job names match the feature manifest and `docs/agent-playbooks/worker-backed-features.md`;
|
||||
- confirm queue names and job names match the owning ticket doc and
|
||||
`docs/agent-playbooks/worker-backed-features.md`;
|
||||
- keep web/API instances from accidentally starting queue processors unless explicitly intended.
|
||||
|
||||
Deployment logs may show package names, command names, health status, and diagnostic codes. They must not echo Redis URLs, database URLs, API keys, tokens, passwords, or secret-shaped examples.
|
||||
|
||||
## Health and diagnostics
|
||||
|
||||
Use worker health output and queue inspection as the primary safe diagnostics. Expected health summaries may include service name, revision, worker enablement, Redis parse/readiness state, database readiness state, configured queue names, dependency codes, and timestamps. The Gitea/Coolify deploy workflow proves live worker revision through Coolify execute-based health JSON and fails closed when execute is unavailable, empty, or non-JSON. Manual queue inspection can help diagnose the failure, but it must not replace the automated worker execute-health proof for accepting a staged or promoted rollout.
|
||||
Use worker health output and queue inspection as the primary safe diagnostics. Expected health summaries may include service name, revision, worker enablement, Redis parse/readiness state, database readiness state, configured queue names, dependency codes, and timestamps. The Gitea/Coolify deploy workflow proves the live worker revision through Coolify's enabled, revision-and-group-bound `cmd` healthcheck. It accepts a rollout only when Coolify reports the deployment healthy and the configured command exactly matches `node apps/worker/dist/deploy-health.js <40-character lowercase Git SHA> <worker-group>` for the deployed immutable revision and resource. The command fails before its network probe when the root-owned image revision, `APP_REVISION`, enablement, or queue group differs. It then calls the running worker's loopback `/readyz`, which proves the PID1 event loop, Redis, database, and required runtime subscribers instead of starting a second Prisma/BullMQ health process. An image alias or Coolify application status without this exact command is not live-revision proof. Manual queue inspection can help diagnose a failure, but it must not replace the automated command-health proof for accepting a staged or promoted rollout.
|
||||
|
||||
Useful redacted troubleshooting facts include:
|
||||
|
||||
@@ -209,7 +221,10 @@ Imports and exports belong on workers when they may exceed request time, need re
|
||||
|
||||
### Browser-backed features
|
||||
|
||||
Browser-backed work must use the approved browser runtime boundary and feature manifest constraints. Required notes include domain allowlist/denylist, timeout policy, screenshot/artifact storage policy, credential handling rules, cleanup jobs, and audit events for start, completion, and failure. Browser runtime diagnostics may include key names, timeout parse status, queue state, and redacted dependency codes only.
|
||||
Browser-backed work must use the approved browser runtime and ticket constraints. Required notes
|
||||
include domain allowlist/denylist, timeout policy, screenshot/artifact storage policy, credential
|
||||
handling, cleanup jobs and audit events. Runtime diagnostics may include only key names, timeout
|
||||
parse status, queue state and redacted dependency codes.
|
||||
|
||||
## Manual E2E boundary
|
||||
|
||||
|
||||
Reference in new issue
Block a user