111 lines
3.2 KiB
Markdown
111 lines
3.2 KiB
Markdown
# Dokploy First-Time Walkthrough
|
|
|
|
This is a first-use setup guide for Dokploy in your environment.
|
|
|
|
## 0) Important Port Constraint
|
|
Dokploy installation expects ports `80`, `443`, and `3000` available on the host where Dokploy is installed.
|
|
|
|
If your Nginx Proxy Manager already uses `80/443` on that same machine, install Dokploy on a separate VM/host (recommended).
|
|
|
|
## 1) Install Dokploy (Operator Step)
|
|
On the target Dokploy server (Linux, root):
|
|
|
|
```bash
|
|
curl -sSL https://dokploy.com/install.sh | sh
|
|
```
|
|
|
|
Then open:
|
|
- `http://<dokploy-host>:3000`
|
|
|
|
Create your admin account.
|
|
|
|
## 2) Create the Web App in Dokploy (Image-Based)
|
|
Create an `Application` service for Fiddy Web and configure:
|
|
- Source type: Docker image
|
|
- Image: `git.nicosaya.com/nalalangan/fiddy/web:main`
|
|
- Internal app port: `3000`
|
|
- Health endpoint: `/api/health/ready`
|
|
|
|
Set environment variables:
|
|
- `DATABASE_URL`
|
|
- `DATABASE_SSL`
|
|
- `ALLOWED_DB_NAMES`
|
|
- `SESSION_COOKIE_NAME`
|
|
- `SESSION_TTL_DAYS`
|
|
- `DEBUG_API=0`
|
|
|
|
## 3) Create the Scheduler App in Dokploy (Image-Based)
|
|
Create a second `Application` service for Scheduler and configure:
|
|
- Source type: Docker image
|
|
- Image: `git.nicosaya.com/nalalangan/fiddy/scheduler:main`
|
|
- No public port required
|
|
|
|
Set environment variables:
|
|
- `DATABASE_URL`
|
|
- `DATABASE_SSL`
|
|
- `ALLOWED_DB_NAMES`
|
|
- `SCHEDULER_POLL_MS` (optional, default `60000`)
|
|
- `SCHEDULER_BATCH_SIZE` (optional, default `100`)
|
|
|
|
## 4) Configure Registry Credentials in Dokploy
|
|
Add your registry credentials in Dokploy registry settings for:
|
|
- registry host: `git.nicosaya.com`
|
|
- username/password (or token)
|
|
|
|
Use the registry in the application configuration so image pulls succeed.
|
|
|
|
## 5) Configure Auto Deploy Hooks
|
|
In both Dokploy applications (Web + Scheduler), enable Auto Deploy and copy each Webhook URL.
|
|
|
|
Set this value in Gitea repo secrets as:
|
|
- `DOKPLOY_DEPLOY_HOOK`
|
|
- `DOKPLOY_SCHEDULER_DEPLOY_HOOK`
|
|
|
|
Set health URL secret too:
|
|
- `DOKPLOY_HEALTHCHECK_URL=https://<public-domain>/api/health/ready`
|
|
|
|
## 6) Wire Gitea Secrets
|
|
In Gitea repository secrets, add:
|
|
- `REGISTRY_USER`
|
|
- `REGISTRY_PASS`
|
|
- `DOKPLOY_DEPLOY_HOOK`
|
|
- `DOKPLOY_SCHEDULER_DEPLOY_HOOK`
|
|
- `DOKPLOY_HEALTHCHECK_URL`
|
|
|
|
The workflow in `.gitea/workflows/deploy-dokploy.yml` will:
|
|
1. build + push web and scheduler images
|
|
2. call Dokploy deploy hook(s)
|
|
3. wait for web ready health via `scripts/wait-for-health.sh`
|
|
|
|
## 7) First Deployment Test
|
|
1. Push `main`.
|
|
2. Confirm Gitea workflow succeeds.
|
|
3. In Dokploy, verify both Web and Scheduler show successful pull/start logs.
|
|
4. Run smoke check:
|
|
|
|
```bash
|
|
scripts/smoke-public-launch.sh https://<domain>
|
|
```
|
|
|
|
Expected:
|
|
- `200` for `/api/health/live` and `/api/health/ready`
|
|
- `X-Request-Id` present
|
|
- `request_id` present in response JSON
|
|
|
|
## 8) Rollback Test (Required Before Public Launch)
|
|
In Dokploy, trigger rollback for Web and Scheduler to previous successful releases, then run smoke check again.
|
|
|
|
Record outcome and reason in your runbook/checklist.
|
|
|
|
## 9) Troubleshooting Fast Path
|
|
- Hook fires but no deploy:
|
|
- verify Auto Deploy enabled in Dokploy app
|
|
- verify hook URL in Gitea secret
|
|
- Image pull fails:
|
|
- verify Dokploy registry credentials
|
|
- verify image path/tag exists
|
|
- Health gate fails:
|
|
- check app logs in Dokploy
|
|
- verify DB connectivity/env vars
|
|
- verify NPM route and TLS
|