WIP

docs/MANUAL_SETUP.md

@@ -0,0 +1,259 @@
+# 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):
+```bash
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
+```
+
+### macOS:
+```bash
+brew services start postgresql
+```
+
+### Windows:
+- Start PostgreSQL service from Services panel
+- Or use pgAdmin
+
+## Step 3: Create Databases
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Copy environment file
+cp .env.example .env
+
+# Edit the .env file
+nano .env
+```
+
+**Minimal .env configuration:**
+```env
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+```bash
+# 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"
+```bash
+# 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"
+```bash
+# Connect to PostgreSQL and create databases
+sudo -u postgres psql
+CREATE DATABASE bookmark_manager;
+CREATE DATABASE bookmark_manager_test;
+\q
+```
+
+### "Authentication failed for user"
+```bash
+# 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"
+```bash
+# 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"
+```bash
+# 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:
+
+```bash
+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:
+   ```bash
+   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.