From 44bb829790bea0ad8f08a127faf66a63a734b50d Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Sun, 25 Jan 2026 00:09:46 -0500
Subject: [PATCH] docs: add environment setup instructions

- Add .env.example file with template for secure configuration
- Update Quick Start section with detailed environment setup
- Provide both .env file and docker-compose variable methods
- Add security notes and password generation commands
- Document default database credentials with security warning
- Include instructions for generating secure JWT secrets and passwords
---
 .env.example |  8 +++++++
 README.md    | 66 +++++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 68 insertions(+), 6 deletions(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f3bfb5f
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,8 @@
+# Environment Variables
+# Copy this file to .env and update the values
+
+# JWT Secret for authentication (generate a secure random string)
+JWT_SECRET=your-secure-jwt-secret-key-here
+
+# PostgreSQL database password
+DBPASS=your-secure-database-password-here
\ No newline at end of file
diff --git a/README.md b/README.md
index d926c86..9e927de 100644
--- a/README.md
+++ b/README.md
@@ -32,16 +32,68 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw
 
 - Docker and Docker Compose
 
-### Running the Application
-
-1. Clone the repository
-2. Run the application:
+### Environment Setup
 
+**Option 1: Create .env file**
 ```bash
-docker-compose up --build
+# Copy the example environment file
+cp .env.example .env
+
+# Edit with your secure values
+nano .env  # or your preferred editor
 ```
 
-3. Access the application at http://localhost:8765
+**Required Environment Variables:**
+- `JWT_SECRET` - Secure random string for JWT authentication
+- `DBPASS` - PostgreSQL database password
+
+### Generating Secure Values
+
+**Generate JWT Secret:**
+```bash
+# Generate 64-byte secure random string
+JWT_SECRET=$(openssl rand -base64 64)
+```
+
+**Generate Database Password:**
+```bash
+# Generate 32-character secure password
+DBPASS=$(openssl rand -base64 32 | tr -d '=' '/+' | cut -c1-32)
+```
+
+**Add to .env:**
+```bash
+echo "JWT_SECRET=$JWT_SECRET" >> .env
+echo "DBPASS=$DBPASS" >> .env
+```
+
+### Running the Application
+
+**Option 1: Using .env file**
+1. Clone the repository
+2. Set up environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your secure values
+   ```
+3. Run the application:
+   ```bash
+   docker-compose up --build
+   ```
+4. Access the application at http://localhost:8765
+
+**Option 2: Using docker-compose variables**
+1. Clone the repository
+2. Set environment variables directly:
+   ```bash
+   export JWT_SECRET="your-secure-jwt-secret-key-here"
+   export DBPASS="your-secure-database-password-here"
+   ```
+3. Run the application:
+   ```bash
+   docker-compose up --build
+   ```
+4. Access the application at http://localhost:8765
 
 ### Database
 
@@ -50,6 +102,8 @@ PostgreSQL runs on port 5432 with default credentials:
 - User: postgres
 - Password: password
 
+**⚠️ Security Note**: Change the default password in production environments! Use the `DBPASS` environment variable to set a secure password.
+
 ## Development
 
 ### Development