Cloud Claw

Cloud Claw is an OpenClaw-oriented backend service scaffold with staged deployment separation.

Current Stage

This repository is currently in Phase 5 (production controlled release gate baseline). The current app/ service is still a minimal runtime skeleton for workflow validation and does not represent formal business integration.

Current Completion Status

• Phase 1 completed:
  • repository normalization, baseline compose files, env template, architecture docs.
• Phase 2 completed:
  • deployment/rollback/healthcheck script baseline for local and CI usage.
• Phase 3 completed:
  • GitHub Actions CI + staging/prod workflow baseline with safety-first boundaries.
• Phase 4 completed:
  • staging real deployment path integrated (secrets-gated remote deployment).
• Phase 5 completed:
  • production release flow added with mandatory workflow dispatch + environment gate.
  • apply/rollback require production secrets and explicit operator intent.
• Production status:
  • production is ready but gated (manual approval + guarded execution).
• Next stage direction:
  • automated release management hardening and deeper rollback safety controls.

Standard Layout

• app/ application source and container build context
• infra/ deployment environment metadata and future IaC artifacts
• scripts/ deployment and operations scripts
• docs/ architecture and operational documentation

Quick Start (Phase 4)

1. Copy .env.example to .env and fill non-secret values.
2. Start staging stack:
   • docker compose -f docker-compose.staging.yml --env-file .env up -d --build
3. Deploy staging through script:
   • bash scripts/deploy-staging.sh --build
4. Validate health manually:
   • bash scripts/healthcheck.sh --url http://127.0.0.1:3000/healthz
5. Production entrypoint (safe plan mode by default):
   • bash scripts/deploy-prod.sh --plan
6. Rollback entrypoint (plan mode unless --apply):
   • bash scripts/rollback.sh --target-image cloud-claw:prod-latest

Notes

• No real secrets are stored in repo.
• Production direct SSH/manual edits are out of scope by policy.
• Staging workflow now includes a secrets-gated real remote deployment path.
• If required staging secrets are missing, remote deployment is explicitly skipped.
• Production deployment script is a controlled entrypoint and only executes apply/rollback under gated workflow conditions.
• Production workflow now supports gated plan/apply/rollback with explicit secret checks.
• Rollback is a minimal safe baseline and requires release metadata for full automation.
• CI workflow runs on pull requests and validates shell scripts plus compose configs.
• Staging workflow supports push on main/master and workflow dispatch, with local demo deploy and real remote path when secrets are present.
• Production workflow is workflow-dispatch only and uses GitHub production environment as manual approval gate structure.
• Architecture reference: docs/ARCHITECTURE.md.
• Project status reference: docs/PROJECT_STATUS.md.
• Runbook reference: docs/RUNBOOK.md.
• Staging acceptance checklist: docs/STAGING_ACCEPTANCE_CHECKLIST.md.
• Production release checklist: docs/PRODUCTION_RELEASE_CHECKLIST.md.
• Production dry-run guide: docs/PRODUCTION_DRY_RUN.md.
• Secrets reference: docs/SECRETS_REQUIRED.md.