turmlibar-calendar/FIX_INSTALLATION.md

# 🔧 Fix Installation Issues on Raspberry Pi

This guide helps fix the "No space left on device" error when installing the Turmli Calendar on Raspberry Pi.

## 🚨 The Problem

When running `pip install` on Raspberry Pi, you're getting:
```
ERROR: Could not install packages due to an OSError: [Errno 28] No space left on device
```

This happens because:
- `/tmp` is in RAM (tmpfs) and limited to ~214MB on your Pi
- The `watchfiles` package requires compilation with Rust
- The build process needs more space than available in `/tmp`

## ✅ Quick Fix

### Option 1: Use the Fix Script (Recommended)

1. Copy the fix script to your Pi:
```bash
# From your development machine
scp fix_install_rpi.sh pi@turmli-pi:/tmp/turmli-calendar/
scp requirements-rpi.txt pi@turmli-pi:/tmp/turmli-calendar/
```

2. Run the fix script:
```bash
cd /tmp/turmli-calendar
sudo ./fix_install_rpi.sh
```

### Option 2: Manual Fix

1. **Clean up temp space:**
```bash
# Clean pip cache
rm -rf /tmp/pip-*
sudo apt-get clean
```

2. **Create a custom temp directory:**
```bash
sudo mkdir -p /opt/turmli-calendar/tmp
sudo chown pi:pi /opt/turmli-calendar/tmp
export TMPDIR=/opt/turmli-calendar/tmp
```

3. **Use the optimized requirements file:**
```bash
cd /opt/turmli-calendar

# Create optimized requirements without problematic packages
cat > requirements-rpi.txt << 'EOF'
fastapi>=0.104.0
uvicorn>=0.24.0
httpx>=0.25.0
icalendar>=5.0.0
jinja2>=3.1.0
python-multipart>=0.0.6
apscheduler>=3.10.0
pytz>=2023.3
EOF
```

4. **Install packages with the custom temp directory:**
```bash
# Activate virtual environment
source /opt/turmli-calendar/venv/bin/activate

# Upgrade pip first
TMPDIR=/opt/turmli-calendar/tmp pip install --upgrade pip wheel setuptools

# Install packages
TMPDIR=/opt/turmli-calendar/tmp pip install \
    --no-cache-dir \
    --prefer-binary \
    --no-build-isolation \
    -r requirements-rpi.txt
```

5. **Clean up:**
```bash
rm -rf /opt/turmli-calendar/tmp
deactivate
```

## 🎯 Alternative: Install Packages One by One

If the above doesn't work, install packages individually:

```bash
cd /opt/turmli-calendar
source venv/bin/activate

# Set temp directory
export TMPDIR=/opt/turmli-calendar/tmp
mkdir -p $TMPDIR

# Install each package separately
pip install --no-cache-dir fastapi
pip install --no-cache-dir uvicorn  # Without [standard] extras
pip install --no-cache-dir httpx
pip install --no-cache-dir icalendar
pip install --no-cache-dir jinja2
pip install --no-cache-dir python-multipart
pip install --no-cache-dir apscheduler
pip install --no-cache-dir pytz

# Clean up
rm -rf $TMPDIR
deactivate
```

## 🚀 Start the Application

After fixing the installation:

### Using systemd service:
```bash
sudo systemctl start turmli-calendar
sudo systemctl status turmli-calendar
```

### Or manually with minimal resources:
```bash
cd /opt/turmli-calendar
./start_minimal.sh
```

### Or directly:
```bash
cd /opt/turmli-calendar
source venv/bin/activate
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1 --log-level warning
```

## 💾 Increase System Resources (Optional)

### 1. Increase Swap Space
```bash
sudo nano /etc/dphys-swapfile
# Change: CONF_SWAPSIZE=512
sudo dphys-swapfile setup
sudo dphys-swapfile swapon
```

### 2. Use Different Temp Location
```bash
# Edit /etc/fstab to mount /tmp on disk instead of RAM
sudo nano /etc/fstab
# Add: tmpfs /tmp tmpfs defaults,noatime,nosuid,size=512m 0 0
```

### 3. Free Up Disk Space
```bash
# Remove unnecessary packages
sudo apt-get autoremove
sudo apt-get clean

# Clear journal logs
sudo journalctl --vacuum-time=7d

# Remove old kernels (if any)
sudo apt-get autoremove --purge
```

## ⚠️ What We're Skipping

The optimized installation skips these optional packages that require compilation:
- `watchfiles` - File watching for auto-reload (not needed in production)
- `websockets` - WebSocket support (not used by this app)
- `httptools` - Faster HTTP parsing (marginal improvement)
- `uvloop` - Faster event loop (nice to have, but not essential)

The application will work perfectly fine without these packages!

## 🔍 Verify Installation

Test that everything is working:

```bash
cd /opt/turmli-calendar
source venv/bin/activate

# Test imports
python -c "import fastapi, uvicorn, httpx, icalendar, jinja2, apscheduler, pytz; print('✓ All modules OK')"

# Test the application
python -c "from main import app; print('✓ Application loads OK')"

deactivate
```

## 📊 Check System Resources

Monitor your system during installation:

```bash
# In another terminal, watch resources
watch -n 1 'free -h; echo; df -h /tmp /opt'
```

## 🆘 Still Having Issues?

1. **Check available space:**
   ```bash
   df -h
   ```

2. **Check memory:**
   ```bash
   free -h
   ```

3. **Try rebooting:**
   ```bash
   sudo reboot
   ```

4. **Use a bigger SD card** (16GB+ recommended)

5. **Consider Raspberry Pi OS Lite** (uses less resources)

## 📝 Notes

- The application uses about 80-120MB RAM when running
- Installation needs about 200-300MB free disk space
- Compilation can use up to 500MB temp space
- Using pre-built wheels (--prefer-binary) avoids most compilation

## ✨ Success!

Once installed, the application will:
- Start automatically on boot
- Restart if it crashes
- Use minimal resources (limited to 256MB RAM)
- Be accessible at `http://your-pi-ip:8000`

Good luck with your installation! 🚀