# Troubleshooting Guide
## Calypso Appliance Installer

## Common Issues

### 1. Installation Fails with "Permission Denied"

**Problem:** Script cannot create directories or files.

**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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/`