calypso/installer/alpha/TROUBLESHOOTING.md

Troubleshooting Guide

Calypso Appliance Installer

Common Issues

1. Installation Fails with "Permission Denied"

Problem: Script cannot create directories or files.

Solution:

# Ensure you're running as root
sudo ./installer/alpha/install.sh

2. Go Not Found After Installation

Problem: Go is installed but not in PATH.

Solution:

# Add to PATH
export PATH=$PATH:/usr/local/go/bin

# Or reload shell
source /etc/profile

3. PostgreSQL Connection Failed

Problem: Database connection errors during installation.

Solution:

# Check PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

# Verify connection
sudo -u postgres psql -c "SELECT version();"

4. Frontend Build Fails

Problem: npm install or build fails.

Solution:

# Clear node_modules and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install
npm run build

5. Service Won't Start

Problem: calypso-api service fails to start.

Solution:

# Check service status
sudo systemctl status calypso-api

# Check logs
sudo journalctl -u calypso-api -n 50

# Verify configuration
sudo -u calypso $INSTALL_PREFIX/current/bin/calypso-api -config /etc/calypso/config.yaml

6. SCST Installation Fails

Problem: SCST kernel module build fails.

Solution:

• Ensure kernel headers are installed: sudo apt-get install linux-headers-$(uname -r)
• SCST may need to be built manually from source
• See: docs/on-progress/scst-installation.md

7. ZFS Installation Fails

Problem: ZFS cannot be installed or loaded.

Solution:

# Install ZFS manually
sudo apt-get update
sudo apt-get install -y zfsutils-linux zfs-dkms

# Load module
sudo modprobe zfs

8. Port Already in Use

Problem: Port 8080 or 3000 already in use.

Solution:

# Check what's using the port
sudo lsof -i :8080
sudo lsof -i :3000

# Change port in config.yaml
sudo nano /etc/calypso/config.yaml

9. Database Migration Fails

Problem: Migrations fail on startup.

Solution:

# Check database permissions
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE calypso TO calypso;"

# Check connection
export PGPASSWORD="your_password"
psql -h localhost -U calypso -d calypso -c "SELECT 1;"

10. Frontend Not Loading

Problem: Web UI shows blank page or errors.

Solution:

• Check API is running: curl http://localhost:8080/api/v1/health
• Check browser console for errors
• Verify frontend assets are in /opt/adastra/calypso/current/web/
• Check reverse proxy configuration (if using)

Getting Help

1. Check logs: sudo journalctl -u calypso-api -f
2. Review installation log
3. Check configuration: sudo cat /etc/calypso/config.yaml
4. Verify services: sudo systemctl status calypso-api
5. Review documentation: docs/alpha/