2.0 KiB
2.0 KiB
Research: Dokploy integration decisions
Decision: Default auto-deploy branch = main
Rationale:
mainis 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
developorstagingbranch (useful for staging environments) — rejected because user selectedmain. - 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)