# 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