docs: replace DEPLOYMENT.md with TROUBLESHOOTING.md and update README

- Remove redundant DEPLOYMENT.md file - Update README.md to reference TROUBLESHOOTING.md for deployment issues - Consolidate deployment documentation into comprehensive troubleshooting guide - Keep essential auto-starting services info in README for quick reference
2026-01-29 16:41:32 -05:00
parent 85e8a132e2
commit 535c1a2fa1
2 changed files with 33 additions and 35 deletions
@@ -0,0 +1,295 @@
+# 🛠️ Troubleshooting Guide
+
+This guide addresses common issues when deploying and running Bookmann on different environments.
+
+## ⚠️ Potential Issues & Solutions
+
+### 1. **Environment Variables Setup**
+
+**Issue:** Missing or incorrect `.env` file
+
+**Solution:**
+```bash
+# 1. Copy the example file
+cp .env.example .env
+
+# 2. Edit with secure values
+nano .env
+# Required:
+JWT_SECRET="your-secure-jwt-secret-key-here"  # 64+ char random string
+DBPASS="your-secure-database-password"           # Strong password
+
+# Optional:
+SERVER_PORT=8765
+DATABASE_HOST=localhost  # For local development
+```
+
+### 2. **Port Conflicts**
+
+**Issue:** Port 8765 already in use
+
+**Solution:**
+```bash
+# Check what's using the port
+lsof -i :8765
+
+# Kill conflicting processes
+sudo kill -9 $(lsof -t -i:8765)
+
+# Or change port in .env
+SERVER_PORT=8766
+```
+
+### 3. **Docker Engine Compatibility**
+
+**Issue:** Using Podman instead of Docker
+
+**Solution:**
+```bash
+# Both work, but for full Docker compatibility:
+# Install Docker Desktop
+# or use Docker instead of podman command
+
+# Podman users: ensure podman-compose is installed
+# Docker and Podman can both use the same compose file
+```
+
+### 4. **Database Permissions**
+
+**Issue:** PostgreSQL fails on foreign key constraints
+
+**Solution:**
+```bash
+# Clean database volume and restart:
+docker compose down -v
+docker volume rm bookmann_postgres_data 2>/dev/null
+docker compose up -d
+
+# Check database logs for errors:
+docker compose logs db
+```
+
+### 5. **Build Dependencies**
+
+**Issue:** `sqlc` or `templ` not in PATH
+
+**Solution:**
+```bash
+# Ensure Go tools are installed correctly
+go version  # Should be 1.25+
+which sqlc  # Check if sqlc is accessible
+which templ  # Check if templ is accessible
+
+# Rebuild if tools are missing:
+docker compose build --no-cache
+```
+
+### 6. **Platform-Specific Issues**
+
+**Issue:** Different OS architectures (ARM vs x86)
+
+**Solution:**
+```bash
+# Check current architecture
+uname -m
+
+# For ARM (Apple M1/M2, Raspberry Pi):
+# Ensure all Go dependencies support ARM
+# May need to rebuild Go modules:
+go mod download && go mod tidy
+
+# Docker automatically handles multi-arch with:
+FROM golang:1.25-alpine AS builder
+# ... rest of Dockerfile remains same
+```
+
+### 7. **Network Connectivity**
+
+**Issue:** Can't connect to localhost
+
+**Solution:**
+```bash
+# Check if containers are running:
+docker compose ps
+
+# Test database connection:
+docker compose exec db psql -U postgres -d bookmann -c "SELECT 1;"
+
+# Test API endpoint:
+curl -s http://localhost:8765/api/libraries/visible
+
+# For remote servers, use actual IP:
+curl -s http://SERVER_IP:8765/api/libraries/visible
+```
+
+## 🚀 Quick Verification
+
+### Basic Health Checks:
+```bash
+# Check container status
+docker compose ps
+
+# Test database connection
+docker compose exec db psql -U postgres -d bookmann -c "SELECT 1;"
+
+# Test API endpoint
+curl -s http://localhost:8765/api/libraries/visible
+
+# Check application logs
+docker compose logs app
+```
+
+### First-Time Setup:
+```bash
+# 1. Clone repository
+git clone <repository-url>
+cd bookmann
+
+# 2. Set up environment
+cp .env.example .env
+# Edit .env with secure values
+
+# 3. Build and run
+docker compose build --no-cache
+docker compose up -d
+
+# 4. Verify
+docker compose ps
+curl -s http://localhost:8765/api/libraries/visible
+```
+
+## 🌐 Production Deployment
+
+### Environment Variables:
+```bash
+# Required production variables
+export JWT_SECRET="your-production-jwt-secret"
+export DBPASS="your-production-db-password"
+
+# Consider using environment files
+cp .env.production .env
+
+# Build with production optimizations
+docker compose -f docker-compose.yml -f docker-compose.prod.yml build
+```
+
+## 📋 Debugging Steps
+
+### Check Application Logs:
+```bash
+# Application logs:
+docker compose logs app
+
+# Database logs:
+docker compose logs db
+
+# Follow logs in real-time:
+docker compose logs -f app
+```
+
+### Check Database Schema:
+```bash
+# Connect to database:
+docker compose exec db psql -U postgres -d bookmann
+
+# List tables:
+\dt
+
+# Check specific table:
+\d media_highlights
+\d media_notes
+
+# Verify foreign keys:
+SELECT
+    tc.constraint_name,
+    tc.table_name,
+    tc.constraint_type,
+    tc.is_deferrable
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu
+     ON tc.constraint_name = kcu.constraint_name
+JOIN information_schema.constraint_column_usage ccu
+     ON tc.constraint_name = ccu.constraint_name
+WHERE tc.table_schema = 'public';
+```
+
+### Test New Features:
+```bash
+# Test notes API:
+curl -s -H "Authorization: Bearer YOUR_TOKEN" \
+     http://localhost:8765/api/media-items/{MEDIA_ID}/notes
+
+# Test highlights API:
+curl -s -H "Authorization: Bearer YOUR_TOKEN" \
+     http://localhost:8765/api/media-items/{MEDIA_ID}/highlights
+```
+
+## 🎯 Architecture Compliance
+
+The current setup follows best practices:
+
+### ✅ **Containerization**
+- Multi-stage Docker builds for smaller images
+- Separate database and application containers
+- Proper volume mounting for data persistence
+- Health checks for service dependencies
+
+### ✅ **Database Design**
+- PostgreSQL with proper foreign key constraints
+- Cascade deletes for data integrity
+- Indexed for performance
+- pgx v5 compatibility
+
+### ✅ **API Design**
+- RESTful endpoints following standards
+- JWT-based authentication
+- Proper HTTP status codes
+- Comprehensive error handling
+
+### ✅ **Build Process**
+- Go modules with vendoring support
+- SQL code generation with sqlc
+- Template generation with templ
+- Asset minification with Tailwind CSS
+
+## 🚀 Expected Behavior
+
+When properly set up, you should see:
+
+1. **Healthy containers**: `docker compose ps` shows "Up" status
+2. **Working API**: `curl http://localhost:8765/api/libraries/visible` returns JSON
+3. **New tables**: `media_highlights` and `media_notes` exist with proper schema
+4. **No port conflicts**: Application binds to port 8765 without errors
+5. **Database ready**: PostgreSQL accepts connections and serves requests
+
+## 🆕 New Features Ready
+
+The highlights and notes functionality provides:
+
+- 📝 **Personal Notes**: Users can create notes on any media item
+- 🖍 **Text Highlighting**: Colorful highlights with position tracking
+- 🔗 **Note-Highlight Links**: Optional associations for detailed annotations
+- 📱 **CRUD Operations**: Full create, read, update, delete for both notes and highlights
+- 🔄 **Backward Compatibility**: All existing ebook endpoints continue working
+- 👥 **Multi-User Support**: Each user has private notes and highlights
+- 🎨 **Color Customization**: Hex color codes for highlights (default yellow)
+
+---
+
+## 🆘 When All Else Fails
+
+### Last Resort Steps:
+1. **Check this guide** for common solutions
+2. **Verify environment variables** are set correctly
+3. **Ensure no port conflicts** on the target machine
+4. **Check Docker compatibility** (Docker vs Podman)
+5. **Review logs** for specific error messages
+6. **Test incrementally** - Start with basic setup, then add complexity
+
+### Get Help:
+- **Check GitHub Issues** for known problems
+- **Verify Docker version** compatibility
+- **Test with minimal setup** before adding customizations
+- **Check system resources** (memory, disk space)
+
+The system is designed to be robust and should work across different platforms with minimal configuration.