ahmido/lms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1fb7b6f69b
lms/specs/001-add-dokploy-deploy/spec.md

6.3 KiB
Raw Blame History

Feature Specification: Dokploy deployment via webhook

Feature Branch: 001-add-dokploy-deploy
Created: 2025-12-15
Status: Draft
Input: User description: "deployment der anwendung findet über dokploy statt dokploy zieht sich die compose und den code von gitea das ist die webook url von dokploy yfürs deployment Webhook URL: https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9"

User Scenarios & Testing (mandatory)

User Story 1 - Auto-deploy on repository push (Priority: P1)

As a developer or release engineer, when I push a new commit to the configured branch in the Gitea repository, Dokploy should be triggered via the provided webhook URL to pull the latest code and docker-compose configuration and deploy the updated application.

Why this priority: Enables a continuous deployment flow and reduces manual deployment overhead.

Independent Test: Push a test commit to the configured branch and verify a deployment run appears in Dokploy and the application becomes available with the new commit.

Acceptance Scenarios:

  1. Given a repository with a valid docker-compose file and Dokploy webhook configured, When a commit is pushed to the configured branch, Then Dokploy receives the webhook and starts a compose-based deployment.
  2. Given Dokploy starts deployment, When the compose deployment completes successfully, Then the application endpoints return the new version/behavior from the pushed commit.

User Story 2 - Manual deploy trigger (Priority: P2)

As an operator, I want to be able to manually trigger the same deployment from Dokploy (or via the webhook) so I can deploy specific tags or commits on demand.

Why this priority: Provides control for releases and hotfixes.

Independent Test: From Dokploy UI or by sending a manual webhook payload referencing a commit/tag, verify the deployment is performed using that commit and the application reflects the targeted state.

Acceptance Scenarios:

  1. Given a specific commit or tag, When an operator triggers a manual deploy, Then Dokploy deploys exactly that commit/tag.

User Story 3 - Failed-deploy notification (Priority: P3)

As a release engineer, when a deployment fails, I want to receive a clear failure notice so I can investigate and roll back if necessary.

Why this priority: Ensures visibility into failed automated deployments.

Independent Test: Simulate a deployment failure (e.g., invalid compose configuration) and verify a notification or visible failure record is produced in Dokploy and logs are accessible.

Acceptance Scenarios:

  1. Given an invalid deploy payload or compose file, When Dokploy attempts the deployment, Then the deployment is marked failed and failure details are available to the operator.

Edge Cases

  • Webhook payload retries from Gitea (duplicate deliveries) — deployments must be idempotent or safely ignored if already in progress for the same commit.
  • Network outage between Dokploy and the repository or target hosts — Dokploy should surface clear error state and allow retry.
  • Partial failures where some services start and others fail — system should report partial success and provide logs.

Requirements (mandatory)

Functional Requirements

  • FR-001: The system MUST accept webhook POSTs from Gitea and map them to a Dokploy compose deployment for the configured feature branch/repository.
  • FR-002: The deployment process MUST pull the repository code and the repository's docker-compose (or compose-equivalent) definition referenced by the repository.
  • FR-003: The system MUST support manual deploy triggers that accept a specific commit hash or tag.
  • FR-004: Deployment runs MUST produce logs and a success/failure status accessible to operators.
  • FR-005: Repeated webhook deliveries for the same commit SHOULD not produce duplicate active deployments (idempotency handling).
  • FR-006: The feature MUST allow configuration of the repository branch or tag to be used for automatic deployments. By default, automatic deployments SHOULD be triggered only for the main branch.
  • FR-007: The feature MUST store the Dokploy Webhook URL and authentication metadata securely (credentials/secrets management). Secrets will be provided and managed as Dokploy project-level secrets.

Key Entities (include if feature involves data)

  • Repository: Gitea repository containing application code and docker-compose configuration. Key attributes: repository URL, default branch, path to compose file.
  • Webhook: HTTP endpoint (Dokploy) that receives push events; includes payload metadata (commit, branch, pusher).
  • Deployment: Dokploy deployment run with attributes: commit hash, status, start/end timestamps, logs.
  • Operator: Person with permission to trigger manual deployments or inspect runs.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: 95% of valid push events to the configured branch result in a Dokploy deployment job starting within 30 seconds of the push.
  • SC-002: 98% of successful deployments complete within 10 minutes (from job start to healthy application state) for the expected workload and compose configuration.
  • SC-003: 90% of deployment failures provide actionable logs and failure reasons accessible within Dokploy's run view.
  • SC-004: Manual deploys using a specific commit or tag succeed and deploy the exact requested code in 95% of attempts during testing.

Assumptions

  • Dokploy instance is reachable and has permission to access the Gitea repository or is configured to pull from the repository.
  • The repository contains a valid docker-compose file at a known path: docker-compose.yml at the repository root.
  • The provided webhook URL is the Dokploy endpoint for compose deployments: https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9.
  • Access control (who can trigger manual deploys) will be handled via Dokploy/Gitea permissions (out of scope for this spec).

Notes

  • This spec focuses on enabling Dokploy-based deployments triggered by Gitea webhooks and manual triggers. It does not prescribe Dokploy internals or implementation details beyond configuration and secure credential handling.