bookmarksite/docs/MANUAL_SETUP.md

Manual Setup Guide

If the setup script is giving you errors, let's do this step by step manually.

Step 1: Install Prerequisites

Node.js

• Download from: https://nodejs.org/
• Install version 16 or higher
• Verify: node --version

PostgreSQL

• Download from: https://www.postgresql.org/download/
• Install version 12 or higher
• Verify: psql --version

Step 2: Start PostgreSQL

Linux (Ubuntu/Debian):

sudo systemctl start postgresql
sudo systemctl enable postgresql

macOS:

brew services start postgresql

Windows:

• Start PostgreSQL service from Services panel
• Or use pgAdmin

Step 3: Create Databases

# Connect to PostgreSQL (try one of these):
sudo -u postgres psql
# OR
psql -U postgres
# OR
psql -U postgres -h localhost

# Once connected, run:
CREATE DATABASE bookmark_manager;
CREATE DATABASE bookmark_manager_test;

# Optional: Create a dedicated user
CREATE USER bookmark_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager TO bookmark_user;
GRANT ALL PRIVILEGES ON DATABASE bookmark_manager_test TO bookmark_user;

# Exit PostgreSQL
\q

Step 4: Backend Setup

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# If npm install fails, try:
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Step 5: Configure Environment

# Copy environment file
cp .env.example .env

# Edit the .env file
nano .env

Minimal .env configuration:

# Server
NODE_ENV=development
PORT=3001

# Database (CHANGE THESE VALUES)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=bookmark_manager
DB_USER=postgres
DB_PASSWORD=your_postgres_password
DB_SSL=false

# JWT (CHANGE THIS TO A LONG RANDOM STRING)
JWT_SECRET=your_very_long_random_secret_key_at_least_32_characters_long
JWT_EXPIRES_IN=24h

# Email (OPTIONAL - you can skip this for now)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=
EMAIL_PASSWORD=
EMAIL_FROM=

# Other settings
ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
BASE_URL=http://localhost:3001
BCRYPT_SALT_ROUNDS=12

Step 6: Test Database Connection

# Test if you can connect with your credentials
psql -h localhost -U postgres -d bookmark_manager

# If successful, you should see:
# bookmark_manager=#

# Exit with:
\q

Step 7: Initialize Database Tables

# Initialize the database
npm run db:init

# If this fails, check what scripts are available:
npm run

# Try checking database status:
npm run db:status

Step 8: Start the Application

# Start in development mode
npm run dev

# You should see something like:
# Server running on port 3001
# Database connected successfully

Step 9: Test the Application

1. Open your browser to: http://localhost:3001
2. You should see the bookmark manager interface
3. Try registering a new account

Troubleshooting Common Issues

"npm install" fails

# Clear npm cache
npm cache clean --force

# Delete node_modules and try again
rm -rf node_modules package-lock.json
npm install

# If still fails, try with legacy peer deps
npm install --legacy-peer-deps

"Database connection failed"

# Check if PostgreSQL is running
sudo systemctl status postgresql  # Linux
brew services list | grep postgresql  # macOS

# Test connection manually
psql -h localhost -U postgres

# Check your .env file values match your PostgreSQL setup

"Database does not exist"

# Connect to PostgreSQL and create databases
sudo -u postgres psql
CREATE DATABASE bookmark_manager;
CREATE DATABASE bookmark_manager_test;
\q

"Authentication failed for user"

# Reset PostgreSQL password
sudo -u postgres psql
ALTER USER postgres PASSWORD 'newpassword';
\q

# Update your .env file with the new password

"Port already in use"

# Find what's using the port
lsof -i :3001

# Kill the process
kill -9 <PID>

# Or change the port in .env
PORT=3002

"Permission denied"

# Make sure you have write permissions
chmod 755 backend/
chmod 644 backend/.env

Minimal Test Without Database

If you're still having database issues, you can test if the basic setup works:

cd backend

# Create a simple test file
echo "console.log('Node.js works!'); console.log('Dependencies:', Object.keys(require('./package.json').dependencies));" > test.js

# Run it
node test.js

# Clean up
rm test.js

Get Specific Help

If you're still having issues, please share:

1. Your operating system
2. The exact command you ran
3. The complete error message
4. Output of these commands:

   node --version
   npm --version
   psql --version
   pwd
   ls -la backend/
   

This will help me give you more specific guidance!

Alternative: Docker Setup (Advanced)

If you're comfortable with Docker, I can provide a Docker setup that handles the database automatically. Let me know if you'd prefer that approach.