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