# 🛠️ Troubleshooting Guide

This guide addresses common issues when deploying and running Bookhoard 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 variables:
# Generate secure passwords (no special characters):
#   JWT_SECRET: openssl rand -hex 32
#   DBPASS: openssl rand -hex 16
JWT_SECRET="your-secure-jwt-secret-key-here"  # 64+ char random string
DBPASS="your-secure-database-password"        # Strong password

# Optional variables (with defaults in docker-compose.yml):
# TEST_MODE=false                   # Disables rate limiting (NEVER in production)
# RATE_LIMIT_ENABLED=true           # Enable/disable rate limiting
# REQUESTS_PER_MINUTE=10            # Rate limit per IP
# BOOKHOARD_CONVERSION_TOOL=/usr/bin/ebook-convert
# BOOKHOARD_CONVERSION_CACHE_TTL=48h
```

### 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. **Container Runtime - Podman vs Docker**

**Issue:** Container runtime compatibility

**Solution:**

```bash
# Podman is recommended (podman-compose works with docker-compose.yml)
# Install podman-compose:
sudo apt install podman-compose  # Debian/Ubuntu

# Docker also works (use docker-compose with docker-compose.yml)
# Both runtimes use the same docker-compose.yml file

# Podman users:
podman-compose up -d

# Docker users:
docker compose up -d
```

### 4. **Database Permissions**

**Issue:** PostgreSQL fails on foreign key constraints

**Solution:**

```bash
# Clean database volume and restart:
# Podman:
podman-compose down -v
podman volume rm bookhoard_postgres_data 2>/dev/null
podman-compose up -d

# Docker:
docker compose down -v
docker volume rm bookhoard_postgres_data 2>/dev/null
docker compose up -d

# Check database logs for errors:
podman-compose logs db  # or: 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:
podman-compose build --no-cache  # or: docker compose build --no-cache
```

### 6. **Conversion Cache Issues**

**Issue:** KEPUB conversion fails or cache problems

**Solution:**

```bash
# Check cache directory exists and is writable
ls -la /var/bookhoard/cache/kepub

# Create cache directory if missing
sudo mkdir -p /var/bookhoard/cache/kepub
sudo chmod 755 /var/bookhoard/cache/kepub

# Clear conversion cache (safe - will reconvert on next download)
sudo rm -rf /var/bookhoard/cache/kepub/*

# Verify kepubify is installed
which kepubify
# or: which ebook-convert

# Conversion service defaults are in docker-compose.yml
# Check if you're overriding them in .env:
grep BOOKHOARD_CONVERSION .env
```

### 7. **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
```

### 8. **Network Connectivity**

**Issue:** Can't connect to localhost

**Solution:**

```bash
# Check if containers are running:
podman-compose ps  # or: docker compose ps

# Test database connection:
podman-compose exec db psql -U postgres -d bookhoard -c "SELECT 1;"  # or: docker compose exec db ...

# 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
podman-compose ps  # or: docker compose ps

# Test database connection
podman-compose exec db psql -U postgres -d bookhoard -c "SELECT 1;"  # or: docker compose exec db ...

# 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 bookhoard

# 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 bookhoard

# 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.