99 lines
6.3 KiB
Markdown
99 lines
6.3 KiB
Markdown
<!--
|
|
Feature spec created by speckit.specify automation
|
|
-->
|
|
# 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. |