WIP

docs/DOCKER_SETUP.md

@@ -0,0 +1,230 @@
+# Docker Setup Guide (Linux)
+
+Since you're using Docker for the database, here's the correct setup process:
+
+## Prerequisites
+
+- **Node.js** (v16+): `sudo apt install nodejs npm` or use NodeSource
+- **Docker**: `sudo apt install docker.io docker-compose-plugin`
+- **Docker Compose**: Included with modern Docker installations
+
+## Step 1: Start the Database with Docker
+
+```bash
+cd backend
+
+# Start PostgreSQL in Docker
+docker compose up -d
+
+# Verify the database is running
+docker compose ps
+
+# You should see:
+# bookmark_postgres   postgres:15   Up   0.0.0.0:5432->5432/tcp
+```
+
+## Step 2: Backend Setup
+
+```bash
+# Install Node.js dependencies
+npm install
+
+# Copy environment file
+cp .env.example .env
+```
+
+## Step 3: Configure Environment for Docker Database
+
+Edit `backend/.env` with these Docker-specific settings:
+
+```env
+# Server Configuration
+NODE_ENV=development
+PORT=3001
+
+# Database Configuration (Docker settings)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=bookmark_manager
+DB_USER=postgres
+DB_PASSWORD=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 for now)
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_SECURE=false
+EMAIL_USER=
+EMAIL_PASSWORD=
+EMAIL_FROM=
+
+# 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 4: Create Test Database
+
+```bash
+# Connect to the Docker PostgreSQL instance
+docker exec -it bookmark_postgres psql -U postgres -d bookmark_manager
+
+# Create the test database
+CREATE DATABASE bookmark_manager_test;
+
+# Exit PostgreSQL
+\q
+```
+
+## Step 5: Initialize Database Tables
+
+```bash
+# Initialize the database schema
+npm run db:init
+
+# Check database status
+npm run db:status
+```
+
+## Step 6: Start the Application
+
+```bash
+# Start the backend server
+npm run dev
+
+# You should see:
+# Server running on port 3001
+# Database connected successfully
+```
+
+## Step 7: Access the Application
+
+Open your browser to: `http://localhost:3001`
+
+The backend now serves the frontend static files automatically - no need for a separate web server!
+
+## Useful Docker Commands
+
+```bash
+# Start the database
+docker compose up -d
+
+# Stop the database
+docker compose down
+
+# View database logs
+docker compose logs postgres
+
+# Connect to database directly
+docker exec -it bookmark_postgres psql -U postgres -d bookmark_manager
+
+# Reset database (removes all data)
+docker compose down -v
+docker compose up -d
+npm run db:init
+```
+
+## Complete Setup Script for Docker
+
+Here's a one-liner setup for Docker:
+
+```bash
+cd backend && \
+docker compose up -d && \
+npm install && \
+cp .env.example .env && \
+echo "Edit .env file now, then run: npm run db:init && npm run dev"
+```
+
+## Troubleshooting Docker Setup
+
+### Docker not running
+```bash
+# Start Docker service
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# Add your user to docker group (logout/login required)
+sudo usermod -aG docker $USER
+```
+
+### Port 5432 already in use
+```bash
+# Check what's using port 5432
+sudo lsof -i :5432
+
+# If it's another PostgreSQL instance, stop it
+sudo systemctl stop postgresql
+
+# Or change the port in docker-compose.yml
+```
+
+### Database connection fails
+```bash
+# Check if container is running
+docker ps | grep postgres
+
+# Check container logs
+docker logs bookmark_postgres
+
+# Test connection
+docker exec -it bookmark_postgres psql -U postgres -c "SELECT version();"
+```
+
+### Permission issues
+```bash
+# Fix Docker permissions
+sudo chmod 666 /var/run/docker.sock
+
+# Or add user to docker group
+sudo usermod -aG docker $USER
+# Then logout and login again
+```
+
+## Environment File for Docker
+
+Here's a ready-to-use `.env` file for the Docker setup:
+
+```env
+NODE_ENV=development
+PORT=3001
+
+# Docker PostgreSQL settings (match docker-compose.yml)
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=bookmark_manager
+DB_USER=postgres
+DB_PASSWORD=password
+DB_SSL=false
+
+# Generate a secure JWT secret
+JWT_SECRET=bookmark_manager_super_secret_jwt_key_change_this_in_production_2024
+JWT_EXPIRES_IN=24h
+
+# Email settings (optional)
+EMAIL_HOST=smtp.gmail.com
+EMAIL_PORT=587
+EMAIL_SECURE=false
+EMAIL_USER=
+EMAIL_PASSWORD=
+EMAIL_FROM=
+
+ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+BASE_URL=http://localhost:3001
+BCRYPT_SALT_ROUNDS=12
+RATE_LIMIT_WINDOW_MS=900000
+RATE_LIMIT_MAX_REQUESTS=100
+AUTH_RATE_LIMIT_MAX=5
+```
+
+This should work perfectly with your Docker setup! Let me know if you encounter any issues.