# 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.