john-okeefe
935b867219
This major update implements a complete user annotation system: ## 🎯 New Features - User notes with position tracking for media items - Text highlighting with customizable colors - Highlight-note associations for detailed annotations - Full CRUD API for both notes and highlights - Backward compatibility with existing ebook endpoints ## 📊 Database Changes - Add media_notes table (id, media_item_id, user_id, content, position, timestamps) - Add media_highlights table (id, media_item_id, user_id, selection_text, start/end_position, color, optional note_id) - Add foreign key relationships with CASCADE deletes - Add proper indexes for performance - Add database schema views for ebook backward compatibility ## 🔧 API Implementation - Complete REST API endpoints for notes and highlights - JWT authentication with proper middleware bypass - Request validation with meaningful error responses - UUID validation and type safety - Support for hex color codes in highlights ## 🧪 Testing & Documentation - Comprehensive test suite covering authentication scenarios - Bruno API collection for manual testing - Detailed testing guide with troubleshooting - Updated documentation in README and TESTING.md ## 📁 Backward Compatibility - Existing ebook endpoints continue working - Database views maintain API contracts - No breaking changes for existing integrations The annotation system is now fully functional and ready for production use.
280 lines
6.9 KiB
Markdown
280 lines
6.9 KiB
Markdown
# 🚀 Deployment & Portability Guide
|
|
|
|
This guide addresses potential issues when building and running Bookmann on another machine.
|
|
|
|
## ✅ Current Status
|
|
|
|
**What Works:**
|
|
- ✅ Docker containers build and start successfully
|
|
- ✅ Database schema loads correctly with all tables
|
|
- ✅ Application connects to database and starts
|
|
- ✅ API endpoints respond correctly
|
|
- ✅ All highlights and notes functionality included
|
|
|
|
## ⚠️ 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
|
|
```
|
|
|
|
## 🔧 Recommended Build Process
|
|
|
|
### 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
|
|
```
|
|
|
|
### For Production Deployment:
|
|
```bash
|
|
# Use production-ready environment 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)
|
|
|
|
---
|
|
|
|
## 📞 If Issues Persist
|
|
|
|
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
|
|
|
|
The system is designed to be robust and should work across different platforms with minimal configuration. |