bookhoard/docs/operations/troubleshooting.md

🛠️ 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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