143 lines
2.9 KiB
Markdown
143 lines
2.9 KiB
Markdown
# 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/`
|
|
|