From d1a8a62c081c3802ad36fab4138d5619c00037bf Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 2 Feb 2026 20:13:05 -0500
Subject: [PATCH] docs: update password generation to use hex encoding

Change openssl rand commands from base64 to hex encoding to avoid
special characters that break URL parsing in database connection strings.

- JWT_SECRET: openssl rand -hex 32
- DBPASS: openssl rand -hex 16

Updated in:
- .env.example
- README.md
- docs/contributing/DEVELOPMENT.md
- docs/operations/troubleshooting.md
---
 .env.example                       | 2 ++
 README.md                          | 5 ++++-
 docs/contributing/DEVELOPMENT.md   | 7 +++++--
 docs/operations/troubleshooting.md | 3 +++
 4 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index cda2140..cfa212d 100644
--- a/.env.example
+++ b/.env.example
@@ -3,9 +3,11 @@
 # Only secrets are required - all other settings have defaults in docker-compose.yml
 
 # JWT Secret for authentication (generate a secure random string)
+# Generate with: openssl rand -hex 32
 JWT_SECRET=your-secure-jwt-secret-key-here
 
 # PostgreSQL database password
+# Generate with: openssl rand -hex 16
 DBPASS=your-secure-database-password-here
 
 # Optional: Override Defaults (defaults are set in docker-compose.yml)
diff --git a/README.md b/README.md
index 97a99dc..9c901af 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,10 @@ cd bookhoard
 
 # 2. Set up environment
 cp .env.example .env
-# Edit .env with your secure JWT_SECRET and DBPASS
+# Generate secure passwords (no special characters):
+#   JWT_SECRET: openssl rand -hex 32
+#   DBPASS: openssl rand -hex 16
+# Edit .env with your generated values
 
 # 3. Start the server
 podman-compose up --build -d  # or: docker-compose up --build -d
diff --git a/docs/contributing/DEVELOPMENT.md b/docs/contributing/DEVELOPMENT.md
index eb2f469..8d8b70a 100644
--- a/docs/contributing/DEVELOPMENT.md
+++ b/docs/contributing/DEVELOPMENT.md
@@ -190,6 +190,9 @@ go test ./... -v
 podman-compose up --build
 
 # Option 2: Direct Go run (requires local PostgreSQL)
+# Generate secure passwords (no special characters):
+#   JWT_SECRET: openssl rand -hex 32
+#   DBPASS: openssl rand -hex 16
 export JWT_SECRET="your-dev-secret"
 export DBPASS="your-db-password"
 go run cmd/server/main.go
@@ -345,8 +348,8 @@ podman-compose build --no-cache
 ### Environment Variables
 
 Required for production:
-- `JWT_SECRET` - 64-byte random string
-- `DBPASS` - Strong database password
+- `JWT_SECRET` - 64-byte random string (generate: `openssl rand -hex 32`)
+- `DBPASS` - Strong database password (generate: `openssl rand -hex 16`)
 - `BASE_URL` - Public URL (e.g., https://bookhoard.example.com)
 
 Optional:
diff --git a/docs/operations/troubleshooting.md b/docs/operations/troubleshooting.md
index d964b81..e2c8370 100644
--- a/docs/operations/troubleshooting.md
+++ b/docs/operations/troubleshooting.md
@@ -17,6 +17,9 @@ cp .env.example .env
 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