Troubleshooting

Common Installation Issues

Database Connection Failed

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Check database exists
sudo -u postgres psql -c '\l' | grep haddock

# Reset database if needed
sudo -u postgres dropdb haddock
sudo -u postgres createdb haddock -O haddock
cd /opt/haddock/api && yarn migrate

Redis Connection Issues

# Verify Redis is running
sudo systemctl status redis-server

# Test Redis connection
redis-cli ping

# Restart Redis if needed
sudo systemctl restart redis-server

API Not Starting

# Check API logs
pm2 logs haddock-api

# Verify API process
pm2 status

# Restart API if needed
pm2 restart haddock-api

Frontend Not Loading

# Check if frontend is built
ls /opt/haddock/frontend/dist

# Rebuild frontend if needed
cd /opt/haddock/frontend
yarn build

# Check Caddy status
sudo systemctl status caddy

Vagrant Issues

# Check libvirt status
sudo systemctl status libvirtd

# Verify vagrant installation
vagrant --version

# Reinstall vagrant-libvirt plugin if needed
vagrant plugin uninstall vagrant-libvirt
vagrant plugin install vagrant-libvirt

Log Files

Important log files to check for troubleshooting:

• Installation log: /var/log/haddock/install.log
• API logs: pm2 logs haddock-api
• Caddy logs: sudo journalctl -u caddy
• Redis logs: sudo journalctl -u redis-server
• PostgreSQL logs: sudo journalctl -u postgresql

Common Error Messages

"Failed to connect to database"

1. Verify PostgreSQL is running
2. Check database credentials in /opt/haddock/api/.env
3. Ensure database exists and user has proper permissions

"Redis connection refused"

1. Check if Redis is running
2. Verify Redis URL in /opt/haddock/api/.env
3. Ensure Redis is listening on correct port

"API health check failed"

1. Check API process status with pm2 status
2. Verify environment variables in /opt/haddock/api/.env
3. Check API logs for specific errors

"Frontend build failed"

1. Check Node.js version (node --version)
2. Verify yarn dependencies (yarn install)
3. Check for build errors in frontend logs

Quick Reset Commands

If you need to reset specific components:

Reset Database

sudo -u postgres dropdb haddock
sudo -u postgres createdb haddock -O haddock
cd /opt/haddock/api && yarn migrate

Reset API

pm2 delete haddock-api
cd /opt/haddock/api
yarn install
yarn build
pm2 start yarn --name haddock-api -- start:prod

Reset Frontend

cd /opt/haddock/frontend
rm -rf node_modules dist
yarn install
yarn build

Getting Help

If you're still experiencing issues:

1. Check the GitHub Issues
2. Submit a new issue with:
   • Installation logs
   • Error messages
   • System information
   • Steps to reproduce