Neon-Desk/COOLIFY.md

Coolify Deployment (Fiscal Clone 2.0)

This repository is deployable on Coolify using the root docker-compose.yml.

What gets deployed

• frontend (Next.js)
• backend (Elysia API + Better Auth)
• worker (durable async job processor)
• postgres (database)

backend and worker auto-run migrations on startup:

• bun run src/db/migrate.ts
• then start API/worker process

Coolify setup

1. Create a Docker Compose app in Coolify.
2. Connect this repository.
3. Use compose file: /docker-compose.yml.
4. Add public domains:

• frontend service on port 3000 (example: https://fiscal.example.com)
• backend service on port 3001 (example: https://api.fiscal.example.com)

Required environment variables

Set these in Coolify before deploy:

POSTGRES_USER=postgres
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=fiscal

DATABASE_URL=postgres://postgres:<strong-password>@postgres:5432/fiscal

# Public URLs
FRONTEND_URL=https://fiscal.example.com
BETTER_AUTH_BASE_URL=https://api.fiscal.example.com
NEXT_PUBLIC_API_URL=https://api.fiscal.example.com

# Security
BETTER_AUTH_SECRET=<openssl rand -base64 32>
SEC_USER_AGENT=Fiscal Clone <ops@your-domain.com>

# Optional OpenClaw/ZeroClaw integration
OPENCLAW_BASE_URL=https://your-openclaw-endpoint
OPENCLAW_API_KEY=<token>
OPENCLAW_MODEL=zeroclaw

# Optional queue tuning
TASK_HEARTBEAT_SECONDS=15
TASK_STALE_SECONDS=120
TASK_MAX_ATTEMPTS=3

Important build note

NEXT_PUBLIC_API_URL is compiled into the frontend bundle at build time. If you change it, trigger a new deploy/rebuild.

The frontend includes a safety fallback: if NEXT_PUBLIC_API_URL is accidentally set to an internal host like http://backend:3001, browser calls will fall back to https://api.<frontend-host>. This is a fallback only; keep NEXT_PUBLIC_API_URL correct in Coolify.

Post-deploy checks

1. API health:

curl -f https://api.fiscal.example.com/api/health

2. Frontend loads and auth screens render.
3. Create user, add watchlist symbol, queue filing sync.
4. Confirm background tasks move queued -> running -> completed in dashboard.

Common pitfalls

• NEXT_PUBLIC_API_URL left as internal hostname (http://backend:3001) causes auth/API failures until fallback or proper config is applied.
• FRONTEND_URL missing/incorrect causes CORS/session issues.
• BETTER_AUTH_BASE_URL must be the public backend URL, not the internal container hostname.
• Deploying frontend and backend on unrelated domains can cause cookie/session headaches. Prefer same root domain (e.g. fiscal.example.com + api.fiscal.example.com).