Skip to main content

Self-Hosting Troubleshooting

Troubleshooting​

502 Bad Gateway​

  • Cause: Nginx on the host cannot reach the Docker containers.
  • Fix: Check if containers are running with docker compose ps. Look at backend logs with docker compose logs api and check ports mapping.

Database Connection Refused​

  • Cause: Wrong credentials in your backend .env or the database container is still starting up.
  • Fix: Verify DB_HOST=db, the non-root DB_USERNAME, DB_PASSWORD, and DB_ROOT_PASSWORD in .env. Check database logs with docker compose logs db.

Compose Cannot Find the Frontend Environment​

  • Cause: web/.env.frontend was not downloaded or was saved in the wrong directory.
  • Fix: From /opt/nusaas, run mkdir -p web && curl -fsSL https://get.nusaas.com/.env.frontend -o web/.env.frontend, edit it, then run docker compose config --quiet.

Browser Requests Are Blocked by CORS​

  • Cause: The frontend origin does not match CORS_ALLOWED_ORIGIN_PATTERNS, or the regex was left unquoted and parsed as a comment.
  • Fix: Use a quoted exact frontend-origin regex such as '#^https://app\.yourdomain\.com$#', then recreate the backend services with docker compose up -d --force-recreate api worker cron ws so they load the changed environment.

WebSockets Disconnect / Not Connecting​

  • Cause: Key mismatch, or Nginx WebSocket upgrade headers are missing.
  • Fix: Verify VITE_REVERB_APP_KEY matches backend REVERB_APP_KEY, and that the public frontend host/port/scheme are api.yourdomain.com, 443, and wss. Ensure Nginx includes the Upgrade and Connection headers.