Troubleshooting

Placeholder — This page will expand into a full troubleshooting guide. Use it as a checklist until detailed steps are written.

Common issues (draft)

App won’t start

• Confirm .env is present and DATABASE_URL is reachable
• Run pnpm db:push or apply migrations after schema changes
• Check Docker services: docker compose ps

Docs collaboration not working

• Ensure pnpm collab:dev (or the production collab service) is running
• Verify PUBLIC_COLLAB_WS_URL matches your public WebSocket URL
• Check reverse-proxy WebSocket upgrade headers if behind Caddy/nginx

File uploads failing

• Confirm MinIO/S3 credentials and bucket name in .env
• For local dev, run pnpm db:start so minio-init creates the bucket

TLS / certificate errors (production)

• DNS must point at the server before Caddy requests a certificate
• Ports 80 and 443 must be open; see Production deployment

Get help

If you are stuck, email hello@wrkin.space with:

• What you expected vs what happened
• Relevant logs (app, collab, Caddy)
• Whether the issue is local dev or production

Related guides

• Local development
• Docker Compose (dev services)