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