Self-Host
Troubleshooting
Common issues and solutions for self-hosted Auxx.ai deployments including Docker, database, and networking problems.
Solutions for common self-hosting issues. For general app issues, see Common issues.
Docker Compose issues
| Problem | Solution |
|---|---|
| Containers won't start | Check docker compose logs <service>. Verify .env has all required secrets set. |
| Database connection refused | Ensure DATABASE_URL uses postgres (Docker service name) as host, not localhost. |
| Redis connection refused | Ensure REDIS_HOST=redis (Docker service name). |
| Port already in use | Change the conflicting port in .env (e.g., APP_PORT=3001). The docker-compose.yml uses ${VAR:-default} interpolation. |
| Web service unhealthy | Check docker compose logs web. Common causes: missing env vars, database not ready (migration service may still be running). |
| MinIO/file upload errors | Verify S3_ENDPOINT=http://minio:9000 and that the minio-init service ran successfully. |
| Migration failures | Check docker compose logs migrate. Ensure database is accessible and DATABASE_URL is correct. |