From 535c1a2fa1440315baba0733ebaa4dec428f74bd Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 29 Jan 2026 16:41:32 -0500
Subject: [PATCH] docs: replace DEPLOYMENT.md with TROUBLESHOOTING.md and
 update README

- Remove redundant DEPLOYMENT.md file
- Update README.md to reference TROUBLESHOOTING.md for deployment issues
- Consolidate deployment documentation into comprehensive troubleshooting guide
- Keep essential auto-starting services info in README for quick reference
---
 README.md                           | 19 +----------
 DEPLOYMENT.md => TROUBLESHOOTING.md | 49 +++++++++++++++++++----------
 2 files changed, 33 insertions(+), 35 deletions(-)
 rename DEPLOYMENT.md => TROUBLESHOOTING.md (87%)

diff --git a/README.md b/README.md
index 79931d5..5329966 100644
--- a/README.md
+++ b/README.md
@@ -284,25 +284,8 @@ go test ./cmd/server/tests -v  # Integration tests only
 
 ## 🐳 Deployment
 
-### Docker Configuration
-```yaml
-# docker-compose.yml
-services:
-  bookmann:
-    build: .
-    ports:
-      - "8765:8765"
-    environment:
-      - JWT_SECRET=${JWT_SECRET}
-      - DBHOST=db
-    depends_on:
-      - db
-    volumes:
-      - /path/to/media:/media  # Mount media directories
-      - /path/to/uploads:/uploads  # Upload directory
-```
+For detailed deployment instructions, Docker configuration, and troubleshooting common issues, see **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)**.
 
-### Auto-Starting Services
 The application automatically starts background services on startup:
 - **Scheduler**: Manages scheduled scanning jobs based on user settings
 - **Watch Mode**: Monitors all library folders for file system changes
diff --git a/DEPLOYMENT.md b/TROUBLESHOOTING.md
similarity index 87%
rename from DEPLOYMENT.md
rename to TROUBLESHOOTING.md
index 9f2a114..89d9755 100644
--- a/DEPLOYMENT.md
+++ b/TROUBLESHOOTING.md
@@ -1,15 +1,6 @@
-# 🚀 Deployment & Portability Guide
+# 🛠️ Troubleshooting 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
+This guide addresses common issues when deploying and running Bookmann on different environments.
 
 ## ⚠️ Potential Issues & Solutions
 
@@ -131,9 +122,24 @@ curl -s http://localhost:8765/api/libraries/visible
 curl -s http://SERVER_IP:8765/api/libraries/visible
 ```
 
-## 🔧 Recommended Build Process
+## 🚀 Quick Verification
 
-### First Time Setup:
+### Basic Health Checks:
+```bash
+# Check container status
+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
+
+# Check application logs
+docker compose logs app
+```
+
+### First-Time Setup:
 ```bash
 # 1. Clone repository
 git clone <repository-url>
@@ -152,9 +158,11 @@ docker compose ps
 curl -s http://localhost:8765/api/libraries/visible
 ```
 
-### For Production Deployment:
+## 🌐 Production Deployment
+
+### Environment Variables:
 ```bash
-# Use production-ready environment variables
+# Required production variables
 export JWT_SECRET="your-production-jwt-secret"
 export DBPASS="your-production-db-password"
 
@@ -268,13 +276,20 @@ The highlights and notes functionality provides:
 
 ---
 
-## 📞 If Issues Persist
+## 🆘 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
+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.
\ No newline at end of file