Merge feature 001-add-dokploy-deploy: Dokploy deployment spec

scripts/simulate_failed_deploy.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Simulate a failed deploy by sending a payload that references a missing compose path
+set -euo pipefail
+
+WEBHOOK_URL=${WEBHOOK_URL:-"https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9"}
+REPO=${REPO:-"org/repo"}
+COMMIT=${COMMIT:-"bad-commit-sha"}
+
+payload=$(cat <<JSON
+{
+  "ref": "refs/heads/main",
+  "commits": [ { "id": "${COMMIT}", "message": "simulate failed deploy" } ],
+  "repository": { "full_name": "${REPO}", "clone_url": "git@gitea.example.com:${REPO}.git" },
+  "compose_path": "nonexistent-compose.yml"
+}
+JSON
+)
+
+echo "Posting simulated failing webhook to $WEBHOOK_URL"
+curl -v -X POST "$WEBHOOK_URL" -H "Content-Type: application/json" -d "$payload"

scripts/test_dokploy_webhook.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Test script: send a sample push webhook to Dokploy
+set -euo pipefail
+
+WEBHOOK_URL=${WEBHOOK_URL:-"https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9"}
+REPO=${REPO:-"org/repo"}
+COMMIT=${COMMIT:-"test-commit-sha"}
+
+payload=$(cat <<JSON
+{
+  "ref": "refs/heads/main",
+  "commits": [ { "id": "${COMMIT}", "message": "test webhook" } ],
+  "repository": { "full_name": "${REPO}", "clone_url": "git@gitea.example.com:${REPO}.git" }
+}
+JSON
+)
+
+echo "Posting test webhook to $WEBHOOK_URL"
+curl -v -X POST "$WEBHOOK_URL" -H "Content-Type: application/json" -d "$payload"

specs/001-add-dokploy-deploy/checklists/deployment-credentials.md

@@ -0,0 +1,14 @@
+# Dokploy Project-Level Secrets (deployment-credentials)
+
+Purpose: document how to add and manage Dokploy project-level secrets that Dokploy will use to access repositories or external resources.
+
+1. In Dokploy, open the project settings for this repository/project.
+2. Navigate to "Secrets" or "Project-level secrets".
+3. Add a secret named `REPO_DEPLOY_KEY` containing a deploy key or token the Dokploy runner can use to clone the Gitea repository (recommended: SSH key or personal access token with repo read access).
+4. Add any other required secrets (e.g., registry credentials) and mark them as masked.
+5. In project configuration, reference the secret names so Dokploy injects them into the deploy environment.
+
+Security notes:
+- Use least-privilege tokens (read-only where possible).
+- Rotate keys periodically and document rotation steps in the runbook.
+- Do not commit secrets into repository files; store them only in Dokploy secrets or an external vault.

specs/001-add-dokploy-deploy/checklists/requirements.md

@@ -0,0 +1,44 @@
+# Specification Quality Checklist: Dokploy deployment via webhook
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-12-15
+**Feature**: [spec.md](specs/001-add-dokploy-deploy/spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)  
+  *Note*: Spec intentionally references Dokploy and docker-compose as required deployment platform details.
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Validation Results
+
+- Replaced clarification markers:
+  - FR-006 default branch set to `main`.
+  - FR-007 secrets to be managed as Dokploy project-level secrets.
+  - Assumption updated: compose file path set to `docker-compose.yml` at repo root.
+
+- Minor note: Spec references Dokploy and docker-compose deliberately because the feature is specifically about integrating with Dokploy; this is intentional and documented above.
+
+## Notes
+
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

specs/001-add-dokploy-deploy/contracts/dokploy-webhook.json

@@ -0,0 +1,22 @@
+{
+  "description": "Dokploy compose deployment webhook details for repo",
+  "dokploy_webhook_url": "https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9",
+  "expected_payload": {
+    "type": "gitea:push",
+    "repository": {
+      "full_name": "<org>/<repo>",
+      "clone_url": "<gitea_clone_url>",
+      "default_branch": "main"
+    },
+    "commits": [
+      {
+        "id": "<commit_sha>",
+        "message": "<commit message>",
+        "timestamp": "<iso8601>",
+        "url": "<commit_url>"
+      }
+    ],
+    "ref": "refs/heads/main"
+  },
+  "notes": "Dokploy must be configured to pull the repository and use `docker-compose.yml` at repo root. Project-level secrets should store any required repository credentials."
+}

specs/001-add-dokploy-deploy/contracts/gitea-webhook-setup.md

@@ -0,0 +1,19 @@
+# Gitea → Dokploy Webhook Setup
+
+Steps to configure the Gitea repository webhook to trigger Dokploy compose deployments:
+
+1. In Gitea, open the repository and go to **Settings → Webhooks**.
+2. Click **Add Webhook** and choose **Gitea** or **Custom** depending on your Gitea version.
+3. Fill in the endpoint URL: `https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9`.
+4. Set **Content Type** to `application/json`.
+5. (Optional but recommended) Add a secret token for payload signing. Store the secret in Dokploy project-level secrets and enable signature validation in Dokploy if supported.
+6. Select events: enable **Push events** (and tag push if you want tag-triggered deploys).
+7. Leave SSL verification enabled unless Dokploy uses a self-signed cert (then configure accordingly).
+8. Save the webhook and use the **Test Delivery** function to send a sample payload.
+
+Verification
+- A successful delivery should return HTTP 2xx from Dokploy. Verify a deployment run appears in Dokploy and that the `commit_sha` from the payload is recorded in the run.
+
+Troubleshooting
+- If Dokploy returns 4xx, check webhook secret/signature and Dokploy project authentication.
+- If Dokploy cannot clone the repo, ensure `REPO_DEPLOY_KEY` is configured and has read access.

specs/001-add-dokploy-deploy/contracts/manual-deploy-payload.json

@@ -0,0 +1,9 @@
+{
+  "ref": "refs/tags/v1.2.3",
+  "commit_sha": "<commit_sha>",
+  "repository": {
+    "full_name": "org/repo",
+    "clone_url": "git@gitea.example.com:org/repo.git"
+  },
+  "note": "Example payload for manual deploy of a specific tag/commit"
+}

specs/001-add-dokploy-deploy/contracts/push-to-deploy.md

@@ -0,0 +1,20 @@
+# Push-to-Deploy: Gitea → Dokploy flow
+
+Flow summary:
+
+1. Developer pushes commit to `main`.
+2. Gitea sends a push webhook to Dokploy (`https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9`).
+3. Dokploy validates the webhook (signature if configured) and enqueues a compose deployment job.
+4. Dokploy clones the repository (using `REPO_DEPLOY_KEY` secret) and reads `docker-compose.yml` at repo root.
+5. Dokploy runs the compose deployment, streams logs, and performs configured healthchecks.
+6. Dokploy marks the run `success` or `failed` and retains logs for troubleshooting.
+
+Payload expectations:
+- `ref` should indicate branch (e.g., `refs/heads/main`).
+- `commits` array includes latest commit with `id` (SHA) and `message`.
+- Dokploy should record `commit_sha` for traceability.
+
+Acceptance criteria for push-to-deploy (US1):
+- A push to `main` starts a Dokploy run within 30s (SC-001).
+- The run uses `docker-compose.yml` at repo root and deploys the commit referenced in the webhook.
+- Duplicate webhook deliveries for the same commit do not start duplicate active deployments.

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

@@ -0,0 +1,38 @@
+# 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 `Webhook`s.
+- 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.

specs/001-add-dokploy-deploy/dokploy-config.md

@@ -0,0 +1,35 @@
+# Dokploy Configuration Recommendations
+
+Repository & Branch
+- `repository`: Gitea clone URL (SSH or HTTPS)
+- `branch`: `main` (default automatic deploy branch)
+- `compose_path`: `docker-compose.yml` (repo root)
+
+Secrets
+- `REPO_DEPLOY_KEY` (SSH private key or token) — Dokploy project-level secret used to clone private repos
+- `REGISTRY_USERNAME`, `REGISTRY_PASSWORD` — optional registry credentials stored as Dokploy secrets
+
+Sample Dokploy project snippet (conceptual)
+
+```yaml
+project:
+  repository: git@gitea.example.com:org/repo.git
+  branch: main
+  compose_path: docker-compose.yml
+  secrets:
+    - name: REPO_DEPLOY_KEY
+      type: ssh_key
+    - name: REGISTRY_PASSWORD
+      type: masked
+  healthcheck:
+    url: https://your-app.example.com/health
+    timeout_seconds: 600
+```
+
+Timeouts & Limits
+- Recommended job timeout: 10 minutes (adjust for heavier builds)
+- Allow Dokploy to stream logs and preserve logs on failure for troubleshooting
+
+Notes
+- Ensure Dokploy runner has network access to Gitea and any external registries.
+- Reference Dokploy secrets by name in project configuration rather than embedding credentials in compose files.

specs/001-add-dokploy-deploy/manual-deploy.md

@@ -0,0 +1,25 @@
+# Manual Deploy: triggering a specific commit or tag
+
+Use cases:
+- Trigger a release for a specific tag.
+- Re-deploy a previous commit for rollback or testing.
+
+Via Dokploy UI:
+1. Open the Dokploy project for this repository.
+2. Choose "New deployment" or similar action.
+3. Enter the commit SHA or select a tag.
+4. Optionally override `compose_path` or environment variables.
+5. Start the deployment and monitor logs.
+
+Via HTTP (example):
+
+```bash
+WEBHOOK=https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9
+curl -X POST "$WEBHOOK" \
+  -H "Content-Type: application/json" \
+  -d @specs/001-add-dokploy-deploy/contracts/manual-deploy-payload.json
+```
+
+Notes:
+- Ensure payload includes `ref` or `commit_sha` field for deterministic deploys.
+- When using HTTP payloads, Dokploy may require authentication or a secret; use Dokploy project-level secrets.

specs/001-add-dokploy-deploy/plan.md

@@ -0,0 +1,95 @@
+Copied plan template to /Users/ahmeddarrazi/Documents/projects/lms/specs/001-add-dokploy-deploy/plan.md
+{"FEATURE_SPEC":"/Users/ahmeddarrazi/Documents/projects/lms/specs/001-add-dokploy-deploy/spec.md","IMPL_PLAN":"/Users/ahmeddarrazi/Documents/projects/lms/specs/001-add-dokploy-deploy/plan.md","SPECS_DIR":"/Users/ahmeddarrazi/Documents/projects/lms/specs/001-add-dokploy-deploy","BRANCH":"001-add-dokploy-deploy","HAS_GIT":"true"}
+ext
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

specs/001-add-dokploy-deploy/quickstart.md

@@ -0,0 +1,25 @@
+# Quickstart: Verify Dokploy deployment for this repo
+
+This quickstart describes the minimal steps to verify Dokploy pulls the repo's `docker-compose.yml` and deploys the application.
+
+Prerequisites:
+- Dokploy project configured with project-level secrets (see checklists/deployment-credentials.md)
+- Dokploy webhook URL: https://system.cloudarix.de/api/deploy/compose/JXSdfeHdc6wBKUEiJrX_9
+- Repository contains `docker-compose.yml` at repository root
+
+Steps:
+
+1. Push a test commit to `main`:
+
+```bash
+git checkout main
+git pull
+git commit --allow-empty -m "test dokploy webhook"
+git push origin main
+```
+
+2. Wait for Dokploy to receive the webhook and start a deployment (watch Dokploy UI or check the project runs).
+
+3. Verify the deployment run completes and application healthchecks succeed (e.g., curl the app endpoint or check service logs).
+
+4. If deployment fails, gather logs from Dokploy run and follow `runbooks/failed-deploy.md`.

specs/001-add-dokploy-deploy/research.md

@@ -0,0 +1,35 @@
+# Research: Dokploy integration decisions
+
+Decision: Default auto-deploy branch = `main`
+
+Rationale:
+- `main` is the safest default for production deployments and matches the user's selection.
+- Using a single canonical branch simplifies webhook filtering and reduces accidental deploys from feature branches.
+
+Alternatives considered:
+- Auto-deploy `develop` or `staging` branch (useful for staging environments) — rejected because user selected `main`.
+- Per-repo configurable branch patterns (`release/*`) — supported but adds configuration complexity; can be added later.
+
+Decision: Secrets management via Dokploy project-level secrets
+
+Rationale:
+- Dokploy project-level secrets centralize credentials, avoid storing secrets in repo, and match the user's selection.
+
+Alternatives considered:
+- Repository-level secrets in Gitea — possible but may require Dokploy to fetch them; increases coupling.
+- External Vault (HashiCorp) — more secure but requires additional integration effort.
+
+Decision: Compose file path = `docker-compose.yml` at repository root
+
+Rationale:
+- Standard convention and chosen by the user; reduces configuration overhead.
+
+Integration Notes & Best Practices
+
+- Webhook security: Prefer a secret/signature on the webhook payload. Configure Dokploy to validate payload signatures when possible.
+- Idempotency: Dokploy or an intermediary should detect duplicate push events by commit SHA and avoid starting duplicate deployments for the same commit.
+- Retries and backoff: Design for webhook retry behavior from Gitea (retries may occur on non-2xx responses) and ensure deploy jobs tolerate duplicate deliveries.
+- Access: Dokploy must either be able to clone the repository (public or via SSH token) or be configured to receive an authenticated pull; store credentials in Dokploy project-level secrets.
+- Healthchecks: Include a minimal application health endpoint for Dokploy to verify deployed service health; document the endpoint in `quickstart.md`.
+
+Open Questions (none remain; user provided selections)

specs/001-add-dokploy-deploy/runbooks/failed-deploy.md

@@ -0,0 +1,14 @@
+# Runbook: Investigating a failed Dokploy deployment
+
+1. Open Dokploy project and find the failed run. Note `commit_sha`, run id, and timestamp.
+2. Stream or download the run logs. Identify service-level errors (image pull failures, healthcheck failures, compose syntax errors).
+3. Common checks:
+   - Image pull/auth errors → verify `REGISTRY_USERNAME`/`REGISTRY_PASSWORD` Dokploy secrets.
+   - Compose parsing errors → inspect `docker-compose.yml` in the referenced commit.
+   - Healthcheck failures → check application logs and health endpoint behavior.
+4. If the failure is due to the new commit, consider rollback: trigger manual deploy for the last successful commit SHA via Dokploy UI or the manual deploy payload.
+5. If credentials are incorrect, rotate secrets in Dokploy and re-run the deployment.
+6. Document root cause in the deployment run notes and open an incident if production impact is high.
+
+Escalation:
+- If unable to resolve within 30 minutes and service is degraded, notify on-call operator and provide run id and logs.

specs/001-add-dokploy-deploy/spec.md

@@ -0,0 +1,99 @@
+<!--
+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.

specs/001-add-dokploy-deploy/tasks.md

@@ -0,0 +1,88 @@
+---
+description: "Task list for feature 001-add-dokploy-deploy"
+---
+
+# Tasks: Dokploy deployment (001-add-dokploy-deploy)
+
+**Input**: Design documents in `specs/001-add-dokploy-deploy/` (spec.md, checklists/)
+
+## Phase 1: Setup (Shared Infrastructure)
+
+- [ ] T001 Create `specs/001-add-dokploy-deploy/plan.md` using `.specify/scripts/bash/setup-plan.sh` (output path: specs/001-add-dokploy-deploy/plan.md)
+- [ ] T002 [P] Create `specs/001-add-dokploy-deploy/quickstart.md` with a minimal deploy verification procedure (file: specs/001-add-dokploy-deploy/quickstart.md)
+- [ ] T003 [P] Add `specs/001-add-dokploy-deploy/contracts/dokploy-webhook.json` documenting the Dokploy webhook URL and expected payload (file: specs/001-add-dokploy-deploy/contracts/dokploy-webhook.json)
+- [ ] T004 Initialize `specs/001-add-dokploy-deploy/checklists/deployment-credentials.md` describing how to add Dokploy project-level secrets (file: specs/001-add-dokploy-deploy/checklists/deployment-credentials.md)
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+- [ ] T005 [P] Create `specs/001-add-dokploy-deploy/data-model.md` describing Repository, Webhook, Deployment entities (file: specs/001-add-dokploy-deploy/data-model.md)
+- [ ] T006 [P] Create `specs/001-add-dokploy-deploy/research.md` capturing Dokploy access requirements and integration notes (file: specs/001-add-dokploy-deploy/research.md)
+- [ ] T007 Create `specs/001-add-dokploy-deploy/dokploy-config.md` with canonical compose file path (`docker-compose.yml`) and Dokploy project config (file: specs/001-add-dokploy-deploy/dokploy-config.md)
+- [ ] T008 [P] Add `specs/001-add-dokploy-deploy/contracts/gitea-webhook-setup.md` with step-by-step instructions for creating the Gitea webhook pointing to Dokploy (file: specs/001-add-dokploy-deploy/contracts/gitea-webhook-setup.md)
+
+---
+
+## Phase 3: User Story 1 - Auto-deploy on repository push (Priority: P1) [US1] 🎯 MVP
+
+**Goal**: Configure automatic Dokploy compose deployments when commits are pushed to `main`.
+
+**Independent Test**: Push a test commit to `main` and verify a Dokploy deployment run starts and completes per `specs/001-add-dokploy-deploy/quickstart.md`.
+
+- [ ] T009 [US1] Add `specs/001-add-dokploy-deploy/contracts/push-to-deploy.md` documenting the exact Gitea -> Dokploy webhook flow and required repo settings (file: specs/001-add-dokploy-deploy/contracts/push-to-deploy.md)
+- [ ] T010 [P] [US1] Add a test helper script `scripts/test_dokploy_webhook.sh` that sends a representative push webhook to the Dokploy URL (file: scripts/test_dokploy_webhook.sh)
+- [ ] T011 [US1] Add `specs/001-add-dokploy-deploy/quickstart.md` step to verify deployment and application health check commands (file: specs/001-add-dokploy-deploy/quickstart.md)
+- [ ] T012 [US1] Add Dokploy project-level secret instructions in `specs/001-add-dokploy-deploy/checklists/deployment-credentials.md` including where to store the webhook URL (file: specs/001-add-dokploy-deploy/checklists/deployment-credentials.md)
+
+---
+
+## Phase 4: User Story 2 - Manual deploy trigger (Priority: P2) [US2]
+
+**Goal**: Allow operators to manually trigger deployments for a specific commit or tag via Dokploy.
+
+**Independent Test**: Trigger a manual deploy for a specified commit/tag and verify deployed commit matches requested commit.
+
+- [ ] T013 [US2] Create `specs/001-add-dokploy-deploy/manual-deploy.md` documenting manual deploy steps in the Dokploy UI and example payloads (file: specs/001-add-dokploy-deploy/manual-deploy.md)
+- [ ] T014 [P] [US2] Add `specs/001-add-dokploy-deploy/contracts/manual-deploy-payload.json` as an example payload for manual triggers (file: specs/001-add-dokploy-deploy/contracts/manual-deploy-payload.json)
+
+---
+
+## Phase 5: User Story 3 - Failed-deploy notification (Priority: P3) [US3]
+
+**Goal**: Provide clear failure visibility and runbooks for operators when deployments fail.
+
+**Independent Test**: Simulate a failing deploy and verify logs and notification entries are available per runbook.
+
+- [ ] T015 [US3] Create `specs/001-add-dokploy-deploy/runbooks/failed-deploy.md` describing how to investigate Dokploy failures and roll back (file: specs/001-add-dokploy-deploy/runbooks/failed-deploy.md)
+- [ ] T016 [P] [US3] Add `scripts/simulate_failed_deploy.sh` to simulate a bad compose deploy for testing failure paths (file: scripts/simulate_failed_deploy.sh)
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+- [ ] T017 [P] Update repository `README.md` with a "Deployment" section linking to `specs/001-add-dokploy-deploy/quickstart.md` (file: README.md)
+- [ ] T018 Commit and push branch `001-add-dokploy-deploy` including `spec.md`, `tasks.md`, and all created docs/scripts (file: N/A - repo action)
+
+---
+
+## Dependencies & Execution Order
+
+- Phase 1 (Setup): start immediately
+- Phase 2 (Foundational): depends on Phase 1 completion
+- Phases 3+ (User stories): depend on Phase 2 completion; once foundation is ready, user stories can be worked on in parallel
+- Final polish: after user stories complete
+
+## Parallel Execution Examples
+
+- While Phase 2 is in progress, tasks marked `[P]` (e.g., T002, T003, T005, T006, T010, T014, T016) can be executed in parallel by different contributors.
+- User story implementation tasks (US1, US2, US3) can proceed concurrently once foundational tasks complete.
+
+## Implementation Strategy
+
+- MVP: Implement Phase 1 + Phase 2 + Phase 3 (US1) first. Validate auto-deploy works end-to-end, then add US2 and US3.
+- Iterative: After US1 is validated, perform US2 and US3 in parallel or by priority depending on team capacity.
+
+---
+
+**Files created by tasks**: All referenced files should be created under `specs/001-add-dokploy-deploy/` unless specified otherwise (e.g., scripts/).