docs: restructure documentation into audience-based portals
BREAKING CHANGE: Documentation URLs have changed New structure: - user/ - End-user documentation (device setup, sync guides, frontend) - developer/ - Developer documentation (API reference, protocols, specs) - operations/ - Operations documentation (deployment, troubleshooting) - contributing/ - Contribution guides Changes: - Created portal INDEX.md files for each audience section - Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md) - Moved API docs to developer/ (api-reference.md, collections-api.md) - Moved sync guide to user/sync-guide.md - Moved troubleshooting to operations/troubleshooting.md - Moved all split API docs to developer/api/ - Renamed protocol files (kobo-protocol.md, koreader-protocol.md) - Added placeholder user guides (frontend, user-areas, settings, admin) - Updated all internal links to new paths - Updated Go code (http_handler.go, navigation.go) for new paths - Updated main INDEX.md for audience-based navigation Benefits: - Clear separation of user and developer documentation - Scalable structure for future user guide expansion - Better organization and discoverability - Audience-specific landing pages Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
This commit is contained in:
@@ -0,0 +1,34 @@
|
||||
# Operations Documentation
|
||||
|
||||
Welcome to the Bookhoard operations documentation. This section contains guides for deploying, maintaining, and troubleshooting Bookhoard instances.
|
||||
|
||||
## 🔧 Deployment
|
||||
|
||||
### Quick Start
|
||||
|
||||
1. **[Troubleshooting Guide](troubleshooting.md)** - Common deployment issues and solutions
|
||||
- Environment variables setup
|
||||
- Port conflicts
|
||||
- Container runtime (Podman)
|
||||
- Network configuration
|
||||
- Performance optimization
|
||||
|
||||
### Additional Deployment Guides
|
||||
|
||||
**[Deployment Guide](deployment.md)** - Comprehensive deployment guide
|
||||
- *Coming Soon*
|
||||
|
||||
## 🛠️ Maintenance
|
||||
|
||||
**[Maintenance Guide](maintenance.md)** - Ongoing operations and maintenance
|
||||
- *Coming Soon*
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
**[Monitoring Guide](monitoring.md)** - Monitoring and alerting
|
||||
- *Coming Soon*
|
||||
|
||||
---
|
||||
|
||||
**Looking for user documentation?** See the [User Portal](../user/INDEX.md)
|
||||
**Need API docs?** See the [Developer Portal](../developer/INDEX.md)
|
||||
@@ -0,0 +1,336 @@
|
||||
# 🛠️ 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:
|
||||
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.
|
||||
Reference in New Issue
Block a user