fiddy/docs/11_DOKPLOY_FIRST_TIME_WALKTHROUGH.md

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

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:

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