add new installer for alpha

installer/alpha/TROUBLESHOOTING.md

@@ -0,0 +1,142 @@
+# 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/`
+