Troubleshooting

Common issues and solutions for Prvue.

Setup Issues

Terraform Errors

Error: “Failed to initialize Terraform”

Ensure Terraform is installed: terraform version
Check Terraform version >= 1.5.0
Verify Digital Ocean token is valid

Error: “Failed to create droplet”

Check Digital Ocean account has sufficient credits
Verify region is available
Check droplet size is available in selected region

Error: “SSH connection failed”

Verify SSH public key is correct
Check firewall allows SSH (port 22)
Wait a few minutes for droplet to fully initialize

Ansible Errors

Error: “Failed to connect to host”

Ensure SSH access works: ssh root@SERVER_IP
Check inventory file is correctly generated
Verify SSH key is added to droplet

Error: “Docker installation failed”

Check internet connectivity on droplet
Verify Ubuntu 22.04 is being used
Check Ansible logs for detailed error

Error: “Orchestrator service failed to start”

Check environment variables are set correctly
Verify Node.js is installed: node --version
Check orchestrator logs: journalctl -u preview-orchestrator -f

Deployment Issues

Webhook Not Triggering

Symptoms: PR opened but no preview deployment Solutions:

Check webhook is configured:
# Via GitHub API or web interface

Verify webhook secret matches:

cat ~/.preview-deployer/config.yml | grep webhook_secret

Check orchestrator logs:

ssh root@SERVER_IP
journalctl -u preview-orchestrator -f

Test webhook manually:

curl -X POST http://SERVER_IP:3000/webhook/github \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=..." \
  -d '{"action":"opened",...}'

Missing or Invalid `preview-config.yml`

Symptoms: Deployment fails with “preview-config.yml is required at repository root but was not found” or a validation error (e.g. “framework is required”, “health_check_path is not valid”). Cause: The orchestrator requires a valid preview-config.yml at the repository root. Required fields: framework, database, health_check_path, app_port, app_port_env, app_entrypoint. Solutions:

Add preview-config.yml in the repo root (see Configuration Reference).
Ensure all required fields are present and valid (e.g. health_check_path must start with /, app_port must be a positive number).
If the file exists but deployment still fails, check orchestrator logs for the exact validation message (e.g. invalid YAML or missing field).

Build Failures

Symptoms: Preview deployment fails during build Solutions:

Check Docker build logs:

ssh root@SERVER_IP
# Work dir is {projectSlug}/pr-{PR_NUMBER} (e.g. myorg-myapp/pr-12)
cd /opt/preview-deployments/{projectSlug}/pr-{PR_NUMBER}
docker compose -p {deploymentId} logs app

Verify Dockerfile exists and is correct
Check build commands in preview-config.yml
Ensure dependencies are installable

`pnpm install --prod` fails (e.g. prepare script / husky)

Symptoms: Build fails at RUN pnpm install --frozen-lockfile --prod (or similar) with exit code 1. Cause: Lifecycle scripts like prepare or postinstall in package.json can depend on devDependencies (e.g. husky). With --prod, devDependencies are not installed, so the script fails when it runs. Fixes (in your app or its Dockerfile):

Husky: Set ENV HUSKY=0 before the install step in your Dockerfile so the prepare script is a no-op in Docker/CI.
General: Move the script’s dependency to dependencies if it must run in production builds, or in the Dockerfile run install with --ignore-scripts and then run only the commands you need (e.g. build).
Prvue: When the repo has no Dockerfile, we inject a default that sets HUSKY=0 so this case is avoided for our template.

Health Check Failures

Symptoms: Containers start but preview URL doesn’t work Solutions:

Verify health check endpoint exists:

curl http://localhost:{APP_PORT}/health

Check health check path in preview-config.yml:

health_check_path: /health # Must match your app's endpoint

Check container logs:

docker logs {projectSlug}-pr-{PR_NUMBER}-app

Verify app is listening on correct port:

docker exec {projectSlug}-pr-{PR_NUMBER}-app netstat -tlnp

Port Conflicts

Symptoms: “Port already in use” error Solutions:

Check allocated ports:

ssh root@SERVER_IP
cat /opt/preview-deployer/deployments.json | jq '.portAllocations'

Find process using port:
lsof -i :{PORT}
Cleanup old deployment (use the full deployment id from GET /api/previews, e.g. my-org-my-app-12):
curl -X DELETE http://SERVER_IP:3000/api/previews/{deploymentId}
See Orchestrator API for full endpoint details.

Nginx Configuration Errors

Symptoms: Preview URL returns 502 Bad Gateway Solutions:

Check nginx config syntax:
ssh root@SERVER_IP nginx -t

Verify preview config exists:

cat /etc/nginx/preview-configs/{projectSlug}-pr-{PR_NUMBER}.conf

Check nginx error logs:
tail -f /var/log/nginx/error.log

Verify app container is running:

docker ps | grep {projectSlug}-pr-{PR_NUMBER}

Test proxy directly:

curl -H "Host: SERVER_IP" http://localhost/{projectSlug}/pr-{PR_NUMBER}/

Runtime Issues

Container Crashes

Symptoms: Preview works initially but stops responding Solutions:

Check container status:

docker ps -a | grep {projectSlug}-pr-{PR_NUMBER}

View container logs:

docker logs {projectSlug}-pr-{PR_NUMBER}-app

Check resource usage:

docker stats {projectSlug}-pr-{PR_NUMBER}-app

Restart container:

cd /opt/preview-deployments/{projectSlug}/pr-{PR_NUMBER}
docker compose restart app

Database Connection Issues

Symptoms: App can’t connect to database Solutions:

Verify database container is running:

docker ps | grep {projectSlug}-pr-{PR_NUMBER}-db

Check database logs:

docker logs {projectSlug}-pr-{PR_NUMBER}-db

Test database connection:

docker exec {projectSlug}-pr-{PR_NUMBER}-db pg_isready -U preview

Verify connection string in app:

docker exec {projectSlug}-pr-{PR_NUMBER}-app env | grep DATABASE_URL

Cleanup Not Working

Symptoms: Old previews not being cleaned up Solutions:

Check cleanup service is running:

ssh root@SERVER_IP
journalctl -u preview-orchestrator | grep cleanup

Verify TTL configuration:

cat ~/.preview-deployer/config.yml | grep cleanup_ttl_days

Manually trigger cleanup (use deployment id from GET /api/previews, e.g. my-org-my-app-12):
curl -X DELETE http://SERVER_IP:3000/api/previews/{deploymentId}

Check deployment age:

cat /opt/preview-deployer/deployments.json | jq '.deployments."{deploymentId}"'

Performance Issues

Slow Builds

Solutions:

Use Docker layer caching
Optimize Dockerfile (multi-stage builds)
Use smaller base images
Cache dependencies in separate layer

High Resource Usage

Solutions:

Reduce max concurrent previews
Lower container resource limits
Use smaller droplet size
Enable cleanup of old previews

Memory Issues

Symptoms: Droplet runs out of memory Solutions:

Check memory usage:
free -h docker stats
Reduce container memory limits
Cleanup old previews
Upgrade droplet size

Security Issues

Webhook Signature Verification Failed

Solutions:

Verify webhook secret matches:

cat ~/.preview-deployer/config.yml | grep webhook_secret

Check GitHub webhook configuration
Verify payload is not modified

Unauthorized Repository Access

Solutions:

Check ALLOWED_REPOS environment variable
Verify repository format: owner/repo
Check orchestrator logs for rejection messages

Debugging Tips

Enable Debug Logging

Set LOG_LEVEL=debug in the orchestrator environment (or set Ansible variable orchestrator_log_level: debug). Debug lines then appear in the same file as info logs: /opt/preview-deployer/logs/orchestrator.log. View them with:

tail -f /opt/preview-deployer/logs/orchestrator.log

To set via systemd override:

ssh root@SERVER_IP
systemctl edit preview-orchestrator
# Add: Environment="LOG_LEVEL=debug"
systemctl daemon-reload
systemctl restart preview-orchestrator

Check All Services

ssh root@SERVER_IP

# Docker
systemctl status docker
docker ps

# Nginx
systemctl status nginx
nginx -t

# Orchestrator
systemctl status preview-orchestrator
tail -n 50 /opt/preview-deployer/logs/orchestrator.log
# Or: journalctl -u preview-orchestrator -n 50

Manual Testing

Test orchestrator API (see Orchestrator API for full endpoint reference):

curl http://SERVER_IP:3000/health
curl http://SERVER_IP:3000/api/previews

Test webhook:

# Generate signature
SECRET="your-webhook-secret"
PAYLOAD='{"action":"opened",...}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST http://SERVER_IP:3000/webhook/github \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=$SIGNATURE" \
  -d "$PAYLOAD"

Getting Help

If you’re still stuck:

Check logs for error messages
Review Architecture Documentation
Check Configuration Reference
Open an issue on GitHub with:
- Error messages
- Logs (sanitized)
- Steps to reproduce
- System information

Common Error Messages

”Repository not in allowed list”

Add repository to ALLOWED_REPOS environment variable
Restart orchestrator service

”Port allocation out of range”

PR number too large (>56,000)
Use smaller PR numbers or upgrade port allocation strategy

”Health check timeout”

Verify health check endpoint exists
Check health check path in config
Increase timeout in docker-manager.ts

”Docker build failed”

Check Dockerfile syntax
Verify all dependencies are available
Check build logs for specific errors

”Nginx reload failed”

Check nginx config syntax: nginx -t
Verify preview config file format
Check nginx error logs

​Setup Issues

​Terraform Errors

​Ansible Errors

​Deployment Issues

​Webhook Not Triggering

​Missing or Invalid preview-config.yml

​Build Failures

​pnpm install --prod fails (e.g. prepare script / husky)

​Health Check Failures

​Port Conflicts

​Nginx Configuration Errors

​Runtime Issues

​Container Crashes

​Database Connection Issues

​Cleanup Not Working

​Performance Issues

​Slow Builds

​High Resource Usage

​Memory Issues

​Security Issues

​Webhook Signature Verification Failed

​Unauthorized Repository Access

​Debugging Tips

​Enable Debug Logging

​Check All Services

​Manual Testing

​Getting Help

​Common Error Messages

​”Repository not in allowed list”

​”Port allocation out of range”

​”Health check timeout”

​”Docker build failed”

​”Nginx reload failed”

Setup Issues

Terraform Errors

Ansible Errors

Deployment Issues

Webhook Not Triggering

Missing or Invalid `preview-config.yml`

Build Failures

`pnpm install --prod` fails (e.g. prepare script / husky)

Health Check Failures

Port Conflicts

Nginx Configuration Errors

Runtime Issues

Container Crashes

Database Connection Issues

Cleanup Not Working

Performance Issues

Slow Builds

High Resource Usage

Memory Issues

Security Issues

Webhook Signature Verification Failed

Unauthorized Repository Access

Debugging Tips

Enable Debug Logging

Check All Services

Manual Testing

Getting Help

Common Error Messages

”Repository not in allowed list”

”Port allocation out of range”

”Health check timeout”

”Docker build failed”

”Nginx reload failed”