Initial commit: File Transformer S3 project with React dashboard and Knative functions

TROUBLESHOOTING.md

@@ -0,0 +1,227 @@
+# Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### 1. Node.js/npm not found
+
+**Error:** `bash: npm: command not found`
+
+**Solution:**
+```bash
+# On Arch Linux
+sudo pacman -S nodejs npm
+
+# On Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Or run the setup script
+./setup.sh
+```
+
+### 2. Python/pip not found
+
+**Error:** `bash: pip: command not found`
+
+**Solution:**
+```bash
+# On Arch Linux
+sudo pacman -S python python-pip
+
+# On Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install -y python3 python3-pip
+
+# Or run the setup script
+./setup.sh
+```
+
+### 3. Docker not found or permission denied
+
+**Error:** `docker: command not found` or `Got permission denied while trying to connect to the Docker daemon`
+
+**Solution:**
+```bash
+# Install Docker
+# On Arch Linux
+sudo pacman -S docker docker-compose
+
+# On Ubuntu/Debian
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+
+# Add user to docker group
+sudo usermod -aG docker $USER
+
+# Start Docker service
+sudo systemctl enable docker
+sudo systemctl start docker
+
+# Log out and back in for group changes to take effect
+```
+
+### 4. Port already in use
+
+**Error:** `Error starting userland proxy: listen tcp 0.0.0.0:3000: bind: address already in use`
+
+**Solution:**
+```bash
+# Check what's using the port
+sudo lsof -i :3000
+
+# Kill the process or change the port in .env file
+# Edit .env and change REACT_APP_PORT to another value like 3001
+```
+
+### 5. Database connection failed
+
+**Error:** `could not connect to server: Connection refused`
+
+**Solution:**
+```bash
+# Check if PostgreSQL is running
+docker-compose ps
+
+# Start the services
+docker-compose up -d
+
+# Check logs
+docker-compose logs postgres
+```
+
+### 6. MinIO connection failed
+
+**Error:** `MinIO connection error`
+
+**Solution:**
+```bash
+# Check if MinIO is running
+docker-compose ps
+
+# Start the services
+docker-compose up -d
+
+# Check MinIO logs
+docker-compose logs minio
+
+# Access MinIO console at http://localhost:9001
+```
+
+### 7. Build failures
+
+**Error:** `npm ERR!` or `pip install` failures
+
+**Solution:**
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Clear pip cache
+pip cache purge
+
+# Reinstall dependencies
+make clean
+make install-deps
+```
+
+### 8. Permission issues
+
+**Error:** `Permission denied` when running scripts
+
+**Solution:**
+```bash
+# Make scripts executable
+chmod +x setup.sh
+chmod +x *.sh
+
+# Check file permissions
+ls -la
+```
+
+### 9. Environment variables not loaded
+
+**Error:** `Environment variable not found`
+
+**Solution:**
+```bash
+# Check if .env file exists
+ls -la .env
+
+# Create .env from template
+cp env.example .env
+
+# Edit .env with your values
+nano .env
+```
+
+### 10. React app not starting
+
+**Error:** `Module not found` or React compilation errors
+
+**Solution:**
+```bash
+# Clear node_modules and reinstall
+cd dashboard
+rm -rf node_modules package-lock.json
+npm install
+
+# Check for missing dependencies
+npm list --depth=0
+```
+
+## Quick Fix Commands
+
+### Reset everything and start fresh:
+```bash
+# Stop all services
+docker-compose down -v
+
+# Clean up
+make clean
+
+# Full setup
+make setup-full
+
+# Start services
+make deploy-local
+```
+
+### Check system status:
+```bash
+# Check all services
+make status
+
+# Check logs
+make logs
+
+# Check dependencies
+which node npm python3 docker
+```
+
+### Development mode:
+```bash
+# Start dashboard in dev mode
+make dev-dashboard
+
+# Start functions in dev mode
+make dev-functions
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. Check the logs: `make logs`
+2. Verify your environment: `make status`
+3. Check the documentation in `README.md`
+4. Ensure all dependencies are installed: `./setup.sh`
+
+## System Requirements
+
+- **OS:** Linux (Arch, Ubuntu, Debian supported)
+- **Node.js:** 16.x or higher
+- **Python:** 3.8 or higher
+- **Docker:** 20.x or higher
+- **Docker Compose:** 2.x or higher
+- **Memory:** At least 4GB RAM
+- **Disk:** At least 10GB free space