bookhoard/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:
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:

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

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

# Clean database volume and restart:
docker compose down -v
docker volume rm bookhoard_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:

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

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

# Check if containers are running:
docker compose ps

# Test database connection:
docker compose exec db psql -U postgres -d bookhoard -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:

# Check container status
docker compose ps

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

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