bookmarksite/docs/TROUBLESHOOTING_SETUP.md

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

# 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)

# 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

# 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

# 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:

# 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

# 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

# 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

# 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:

   psql -h localhost -U postgres -d bookmark_manager
   

Error: "ECONNREFUSED" or "Connection refused"

Solution:

1. PostgreSQL is not running:

   # Ubuntu/Debian:
   sudo systemctl start postgresql
   
   # macOS:
   brew services start postgresql
   

2. Wrong host/port in .env:

   DB_HOST=localhost
   DB_PORT=5432
   

Error: "database does not exist"

Solution:

# 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:

   sudo -u postgres psql
   

3. Reset postgres password if needed:

   sudo -u postgres psql
   ALTER USER postgres PASSWORD 'newpassword';
   

Error: "npm install" fails

Solution:

# 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:

# 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:

# 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:

# 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.