WIP

docs/TROUBLESHOOTING_SETUP.md

@@ -0,0 +1,304 @@
+# Setup Troubleshooting Guide
+
+## Step-by-Step Manual Setup
+
+Let's go through each step manually to identify where the issue occurs.
+
+### Step 1: Check Prerequisites
+
+```bash
+# Check Node.js version (should be 16+)
+node --version
+
+# Check npm version
+npm --version
+
+# Check if PostgreSQL is installed and running
+psql --version
+
+# Check if PostgreSQL service is running
+# On Ubuntu/Debian:
+sudo systemctl status postgresql
+
+# On macOS:
+brew services list | grep postgresql
+
+# On Windows:
+# Check Services in Task Manager for PostgreSQL
+```
+
+### Step 2: Database Setup (Most Common Issue)
+
+```bash
+# Start PostgreSQL if not running
+# Ubuntu/Debian:
+sudo systemctl start postgresql
+
+# macOS:
+brew services start postgresql
+
+# Connect to PostgreSQL (try different approaches)
+# Option 1: Default postgres user
+sudo -u postgres psql
+
+# Option 2: Your system user
+psql -U postgres
+
+# Option 3: Specify host
+psql -h localhost -U postgres
+
+# Once connected, create databases:
+CREATE DATABASE bookmark_manager;
+CREATE DATABASE bookmark_manager_test;
+
+# Create a user (optional but recommended)
+CREATE USER bookmark_user WITH PASSWORD 'secure_password_123';
+GRANT ALL PRIVILEGES ON DATABASE bookmark_manager TO bookmark_user;
+GRANT ALL PRIVILEGES ON DATABASE bookmark_manager_test TO bookmark_user;
+
+# List databases to verify
+\l
+
+# Exit PostgreSQL
+\q
+```
+
+### Step 3: Backend Setup
+
+```bash
+# Navigate to backend directory
+cd backend
+
+# Install dependencies (this might take a while)
+npm install
+
+# If npm install fails, try:
+npm install --legacy-peer-deps
+
+# Or clear cache first:
+npm cache clean --force
+npm install
+```
+
+### Step 4: Environment Configuration
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit the .env file with your actual values
+nano .env
+# OR
+code .env
+# OR
+vim .env
+```
+
+**Edit your `.env` file with these values:**
+
+```env
+# Server Configuration
+NODE_ENV=development
+PORT=3001
+
+# Database Configuration (CHANGE THESE)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=bookmark_manager
+DB_USER=postgres
+DB_PASSWORD=your_actual_postgres_password
+DB_SSL=false
+
+# JWT Configuration (CHANGE THIS)
+JWT_SECRET=your_very_long_random_secret_key_at_least_32_characters_long
+JWT_EXPIRES_IN=24h
+
+# Email Configuration (OPTIONAL - can skip for now)
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_SECURE=false
+EMAIL_USER=your_email@gmail.com
+EMAIL_PASSWORD=your_app_password
+EMAIL_FROM=your_email@gmail.com
+
+# Application Configuration
+ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+BASE_URL=http://localhost:3001
+
+# Security Configuration
+BCRYPT_SALT_ROUNDS=12
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+AUTH_RATE_LIMIT_MAX=5
+```
+
+### Step 5: Test Database Connection
+
+```bash
+# Test if you can connect to the database with your credentials
+psql -h localhost -U postgres -d bookmark_manager
+
+# If this works, exit with:
+\q
+```
+
+### Step 6: Initialize Database Tables
+
+```bash
+# Try to initialize the database
+npm run db:init
+
+# If this fails, let's check what's available:
+npm run
+
+# Try individual database commands:
+npm run db:status
+npm run db:diagnostics
+```
+
+### Step 7: Start the Application
+
+```bash
+# Try starting in development mode
+npm run dev
+
+# If that fails, try:
+npm start
+
+# If both fail, try running the server directly:
+node server.js
+```
+
+## Common Error Solutions
+
+### Error: "Database not connected"
+
+**Solution:**
+1. Make sure PostgreSQL is running
+2. Check your database credentials in `.env`
+3. Test connection manually:
+   ```bash
+   psql -h localhost -U postgres -d bookmark_manager
+   ```
+
+### Error: "ECONNREFUSED" or "Connection refused"
+
+**Solution:**
+1. PostgreSQL is not running:
+   ```bash
+   # Ubuntu/Debian:
+   sudo systemctl start postgresql
+   
+   # macOS:
+   brew services start postgresql
+   ```
+
+2. Wrong host/port in `.env`:
+   ```env
+   DB_HOST=localhost
+   DB_PORT=5432
+   ```
+
+### Error: "database does not exist"
+
+**Solution:**
+```bash
+# Connect to PostgreSQL and create the database
+sudo -u postgres psql
+CREATE DATABASE bookmark_manager;
+CREATE DATABASE bookmark_manager_test;
+\q
+```
+
+### Error: "authentication failed"
+
+**Solution:**
+1. Check your PostgreSQL password
+2. Try connecting as postgres user:
+   ```bash
+   sudo -u postgres psql
+   ```
+3. Reset postgres password if needed:
+   ```bash
+   sudo -u postgres psql
+   ALTER USER postgres PASSWORD 'newpassword';
+   ```
+
+### Error: "npm install" fails
+
+**Solution:**
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Delete node_modules and package-lock.json
+rm -rf node_modules package-lock.json
+
+# Reinstall
+npm install
+
+# If still fails, try:
+npm install --legacy-peer-deps
+```
+
+### Error: "Port 3001 already in use"
+
+**Solution:**
+```bash
+# Find what's using the port
+lsof -i :3001
+
+# Kill the process
+kill -9 <PID>
+
+# Or change the port in .env:
+PORT=3002
+```
+
+## Minimal Test Setup
+
+If you're still having issues, let's try a minimal setup:
+
+```bash
+# 1. Just test if Node.js works
+cd backend
+node -e "console.log('Node.js works!')"
+
+# 2. Test if we can connect to PostgreSQL
+psql -U postgres -c "SELECT version();"
+
+# 3. Test if npm install worked
+npm list --depth=0
+
+# 4. Test if we can start the server without database
+# Comment out database initialization in server.js temporarily
+```
+
+## Get Help
+
+**Please share the specific error messages you're seeing, including:**
+
+1. What command you ran
+2. The exact error message
+3. Your operating system
+4. Node.js version (`node --version`)
+5. PostgreSQL version (`psql --version`)
+
+**Common commands to get system info:**
+```bash
+# System info
+uname -a
+
+# Node.js version
+node --version
+
+# npm version
+npm --version
+
+# PostgreSQL version and status
+psql --version
+sudo systemctl status postgresql  # Linux
+brew services list | grep postgresql  # macOS
+```
+
+This will help me provide more specific solutions for your setup issues.