Skip to content

SETUP.md

Latest commit

 

History

History
400 lines (306 loc) · 11.5 KB

SETUP.md

File metadata and controls

400 lines (306 loc) · 11.5 KB

The Beans - Complete Setup Guide

Welcome to The Beans - a modern coffee roaster discovery platform! This comprehensive guide will help you get the entire development environment up and running.

Prerequisites

Required Software

Optional (for local development without Docker)

Recommended Setup (Docker - Preferred)

Critical: Docker provides the most reliable development environment. Container restarts are required for code changes to take effect.

Quick Start

  1. Clone the repository

    git clone https://github.com/thephm/the-beans.git
cd the-beans

  2. Start all services

    docker-compose up --build

  3. Access the applications

Development Workflow

Essential commands for Docker development:

# After making frontend changes
docker-compose restart client

# After making backend changes
docker-compose restart server

# Rebuild everything if needed
docker-compose up --build

# Stop all services
docker-compose down

# View logs
docker-compose logs -f client    # Frontend logs
docker-compose logs -f server    # Backend logs

Database Management

# Connect to PostgreSQL shell
docker exec -it the-beans-database-1 psql -U beans_user -d the_beans_db

# Run database migrations
docker-compose exec server npx prisma migrate dev

# Generate Prisma client
docker-compose exec server npx prisma generate

# Reset database (careful!)
docker-compose exec server npx prisma migrate reset

# Check admin users
docker exec -it the-beans-database-1 psql -U beans_user -d the_beans_db -c "SELECT email, username, role FROM users WHERE role = 'admin';"

Alternative Setup (Local Development)

Not Recommended: Use this only if Docker is unavailable. Local setup is more complex and prone to environment issues.

Prerequisites

Setup Steps

  1. Install dependencies

    # Install all dependencies
npm run setup

# Or install manually
cd client && npm install
cd ../server && npm install

  2. Environment configuration

    # Copy environment templates
cp server/.env.example server/.env
cp client/.env.example client/.env.local

  3. Configure database connection

    • Edit server/.env with your PostgreSQL credentials
    • Ensure PostgreSQL is running locally

  4. Initialize database

    cd server
npx prisma generate
npx prisma migrate dev
npx prisma db seed

  5. Start development servers

    # From root directory - starts both frontend and backend
npm run dev

# Or start individually
cd client && npm run dev    # Frontend on :3000
cd server && npm run dev    # Backend on :5000

Environment Variables Guide

Server Configuration (server/.env)

# Database
DATABASE_URL="postgresql://beans_user:2w3E4r%T@localhost:5432/the_beans_db"

# Authentication
JWT_SECRET="your-super-secure-jwt-secret-key-here"
JWT_EXPIRES_IN="7d"

# Image Storage (Cloudinary)
CLOUDINARY_CLOUD_NAME="your_cloud_name"
CLOUDINARY_API_KEY="your_api_key"  
CLOUDINARY_API_SECRET="your_api_secret"

# Email Configuration (for notifications and contact form)
CONTACT_US_EMAIL="your_contact_email@example.com"  # Email address that receives Contact Us form submissions
ADMIN_EMAIL="admin@example.com"                    # Admin email for notifications
SMTP_HOST="smtp.gmail.com"                         # SMTP server hostname
SMTP_PORT="587"                                     # SMTP server port (typically 587 for TLS)
SMTP_USER="your-email@gmail.com"                   # SMTP authentication username
SMTP_PASS="your-app-password"                      # SMTP authentication password

# URLs
CLIENT_URL="http://localhost:3000"                 # Frontend URL (for CORS)
FRONTEND_URL="http://localhost:3000"               # Frontend URL (for email links)
API_URL="http://localhost:5000"                    # Backend API URL (for Swagger docs)
CORS_ORIGIN="http://localhost:3000"                # Allowed CORS origins (comma-separated)

# Server Configuration
PORT="5000"
NODE_ENV="development"

Client Configuration (client/.env.local)

# API Connection
NEXT_PUBLIC_API_URL="http://localhost:5000"

# Image Storage (Cloudinary - Public)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="your_cloud_name"

# Maps (Optional)
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY="your_google_maps_api_key"

# App Configuration
NEXT_PUBLIC_APP_NAME="The Beans"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Manual Database Setup (Local Development Only)

Note: Skip this if using Docker - the database is automatically configured.

1. Install PostgreSQL

# Windows: Download from postgresql.org
# macOS
brew install postgresql

# Linux
sudo apt-get install postgresql postgresql-contrib

2. Create Database and User

-- Connect to PostgreSQL
psql -U postgres

-- Create user and database
CREATE USER beans_user WITH PASSWORD 'secure_password_here';
CREATE DATABASE the_beans_db OWNER beans_user;
GRANT ALL PRIVILEGES ON DATABASE the_beans_db TO beans_user;

-- Exit
\q

3. Update Environment Variable

# In server/.env
DATABASE_URL="postgresql://beans_user:secure_password_here@localhost:5432/the_beans_db"

External API Keys Setup

Email Configuration (Required for Contact Form & Notifications)

The application uses SMTP for sending emails via the Contact Us form and user notifications. You'll need:

  1. Choose an Email Provider:

    • Gmail: Use App Passwords
    • Fastmail: Generate an app-specific password
    • SendGrid/Mailgun: Use their SMTP credentials
    • Other providers: Use your SMTP server details

  2. Configure Environment Variables in server/.env:

    CONTACT_US_EMAIL="contact@yourdomain.com"  # Where contact form emails go
ADMIN_EMAIL="admin@yourdomain.com"         # For admin notifications
SMTP_HOST="smtp.gmail.com"                 # Your SMTP server
SMTP_PORT=587                              # Usually 587 (TLS) or 465 (SSL)
SMTP_USER="your-email@gmail.com"           # Your email/username
SMTP_PASS="your-app-password"              # App password or SMTP password

  3. Gmail-Specific Setup:

    • Enable 2-factor authentication in your Google account
    • Go to App Passwords
    • Generate a new app password for "Mail"
    • Use this generated password as SMTP_PASS

  4. Test Email Configuration:

    # After configuring, restart the server
docker-compose restart server

# Test by submitting the Contact Us form
# Or check server logs for email-related errors
docker logs the-beans-server-1

Cloudinary (Image Storage)

  1. Sign up at cloudinary.com
  2. Get credentials from your dashboard:
    • Cloud Name
    • API Key
    • API Secret
  3. Add to environment files (both server and client)

Google Maps API (Optional)

  1. Go to Google Cloud Console
  2. Enable APIs: Maps JavaScript API, Geocoding API, Places API
  3. Create API Key with appropriate restrictions
  4. Add to client/.env.local

Development URLs

👤 Default Admin Credentials

  • Email: admin@example.com
  • Password: admin123

Production Deployment

Render.com Deployment (Recommended)

One-Click Deployment with Blueprint

  1. Fork/Clone the repository to your GitHub account
  2. Sign up at Render.com and connect your GitHub
  3. Create New > Blueprint and select your repository
  4. Review Services - Render will detect render.yaml and show:
    • the-beans-api (Backend API)
    • the-beans-frontend (Next.js Frontend)
    • the-beans-db (PostgreSQL Database)
  5. Configure Environment Variables: 
    CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_secret
  6. Deploy - All services will be created and deployed automatically

Manual Service Configuration

If you prefer manual setup:

  1. Create PostgreSQL Database service
  2. Create Web Service for backend (Express.js)
  3. Create Web Service for frontend (Next.js)
  4. Configure environment variables for each service

Docker-Based Deployment

Alternative deployment using Docker containers with docker-compose.yml.

Production Database

# Run migrations on production
npx prisma migrate deploy
npx prisma generate

Troubleshooting

Docker Issues

  • Containers won't start: Ensure Docker Desktop is running
  • Database connection fails: Check if database container is healthy
  • Changes not visible: Restart the appropriate container
  • Port conflicts: Ensure ports 3000, 5000, 5432 are available

Local Development Issues

  • PostgreSQL connection: Verify database is running and credentials are correct
  • Node modules: Delete node_modules and run npm install
  • Prisma issues: Run npx prisma generate after schema changes
  • API calls fail: Check if backend is running on correct port

Useful Commands

# Check what's running on ports
netstat -an | findstr :3000
netstat -an | findstr :5000

# Reset everything (Docker)
docker-compose down -v
docker-compose up --build

# Reset database
docker-compose exec server npx prisma migrate reset
  1. Add PostgreSQL database service
  2. Deploy!

Domain Setup (Cloudflare)

  1. Purchase your domain
  2. Add it to Cloudflare
  3. Update DNS records to point to your deployments
  4. Enable SSL/TLS

Features Overview

Current Features:

  • Beautiful purple-themed UI
  • User authentication (signup/login)
  • Roaster discovery and profiles
  • Location-based search
  • Responsive design (mobile/desktop)
  • RESTful API with Swagger docs

Coming Soon:

  • Cafe profiles linked to roasters
  • Photo uploads
  • User reviews and ratings
  • Push notifications
  • Advanced filtering
  • Map view
  • Progressive Web App (PWA)

Troubleshooting

Common Issues

Database Connection Error

  • Check PostgreSQL is running
  • Verify DATABASE_URL format
  • Ensure database exists

Module Not Found Errors

  • Run npm run setup from root directory
  • Check Node.js version (18+)

API Errors

  • Check server logs in terminal
  • Verify environment variables
  • Check API documentation at /api-docs

Support

For help or questions:

Happy coding!

do i need to put quotes around my api key in the client/.env files?

No, you don't need quotes around API keys in .env files!