lms/specs/001-add-dokploy-deploy/data-model.md

Data Model: Dokploy deployment integration

Entities

• Repository

  • Attributes: id, name, full_name, clone_url, default_branch (string, e.g., main), compose_path (string, default docker-compose.yml)
  • Validation: clone_url must be reachable; compose_path must exist in repository at deploy time

• Webhook

  • Attributes: id, target_url (Dokploy webhook URL), secret (reference to secret store), events (array, e.g., [push])
  • Validation: target_url must be an HTTPS URL; secret must be present when webhook signs payloads

• Deployment

  • Attributes: id, repository_full_name, commit_sha, ref (branch), status (pending, running, success, failed), started_at, finished_at, logs_url
  • Validation: commit_sha required for deterministic deploys; status transitions enforced (pending→running→(success|failed))

• Secret

  • Attributes: name, type (ssh_key|token|registry), reference (Dokploy secret id)
  • Validation: secrets must not be stored in repo; must be referenced by name in Dokploy config

• Operator

  • Attributes: username, role (developer|operator|admin), contact (email)

Relationships

• A Repository has one or more configured Webhooks.
• A Webhook creates zero-or-more Deployment runs over time.
• A Deployment may reference one or more Secret entries (e.g., REPO_DEPLOY_KEY, registry creds).

State Transitions (Deployment)

• pending -> running when Dokploy picks up the job
• running -> success when all services healthy
• running -> failed when one or more compose services fail to start or healthchecks fail

Notes

• The data model is intentionally lightweight; Dokploy manages most runtime state. These entities are useful for documenting contracts, runbooks, and acceptance tests.