Skip to content

SETUP.md

Latest commit

 

History

History
292 lines (215 loc) · 6.38 KB

SETUP.md

File metadata and controls

292 lines (215 loc) · 6.38 KB
Raw

EVFlow Setup Guide

Quick Start

Follow these steps to get EVFlow running on your local machine.

1. Prerequisites Check

Make sure you have:

  • ✅ Node.js 18+ installed (node --version)
  • ✅ PostgreSQL 14+ installed and running
  • ✅ npm installed (npm --version)

2. Database Setup

Install PostgreSQL with PostGIS

Windows:

  1. Download PostgreSQL from https://www.postgresql.org/download/windows/
  2. During installation, make sure to install the PostGIS extension via Stack Builder
  3. Remember your postgres password!

Verify Installation:

psql --version

Create the Database

Option 1 - Using the setup script (recommended):

cd backend
npm run db:setup

Option 2 - Manual setup:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE evflow;

# Connect to evflow database
\c evflow

# Enable PostGIS
CREATE EXTENSION IF NOT EXISTS postgis;

# Exit psql
\q

# Run schema
psql -U postgres -d evflow -f database/schema.sql

3. Environment Configuration

Create a .env file in the root directory:

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=evflow
DB_USER=postgres
DB_PASSWORD=your_postgres_password_here

# JWT Secret (change this!)
JWT_SECRET=change-this-to-a-random-secret-key

# Server Configuration
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:3000

# Mapbox Token (REQUIRED for maps)
# Get your free token from: https://account.mapbox.com/access-tokens/
NEXT_PUBLIC_MAPBOX_TOKEN=pk.your_mapbox_token_here

# OpenChargeMap API (Optional)
# Get API key from: https://openchargemap.org/site/loginprovider/register
OPENCHARGE_API_KEY=your_opencharge_api_key_here
OPENCHARGE_API_URL=https://api.openchargemap.io/v3

# Frontend API URL
NEXT_PUBLIC_API_URL=http://localhost:5000

4. Get Your Mapbox Token (REQUIRED)

  1. Go to https://account.mapbox.com/
  2. Sign up for a free account
  3. Go to "Access tokens" section
  4. Copy your default public token
  5. Paste it in .env as NEXT_PUBLIC_MAPBOX_TOKEN

5. Seed the Database

cd backend
npm run db:seed

This will add:

  • 15 popular EV models (Tesla, Nissan, Hyundai, etc.)
  • Sample charging station data will be synced from OpenChargeMap when you use the app

6. Start the Application

Terminal 1 - Backend:

cd backend
npm run dev

You should see:

🚀 EVFlow API server running on port 5000
✅ Database connected successfully

Terminal 2 - Frontend:

npm run dev

You should see:

▲ Next.js 14.x.x
- Local:        http://localhost:3000

7. Access the Application

Open your browser and go to:

8. Create Your First Account

  1. Click "Get Started" or "Register"
  2. Fill in your details
  3. You'll be redirected to the dashboard
  4. Allow location access when prompted (or it will use a default location)

9. Sync Charging Stations

The app will automatically attempt to load nearby stations based on your location using the OpenChargeMap API.

If you want to manually sync stations for a specific location, you can use the API:

curl -X POST http://localhost:5000/api/stations/sync \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 37.7749,
    "longitude": -122.4194,
    "radius": 10
  }'

Troubleshooting

Database Connection Issues

Error: "password authentication failed"

  • Check your DB_PASSWORD in .env matches your PostgreSQL password
  • Make sure PostgreSQL is running: pg_ctl status

Error: "database evflow does not exist"

  • Run npm run db:setup in the backend directory

Map Not Loading

Blank map or "Error loading map"

  • Check that NEXT_PUBLIC_MAPBOX_TOKEN is set correctly in .env
  • Verify your Mapbox token is valid at https://account.mapbox.com/
  • Restart the frontend server after adding the token

No Stations Showing

Empty station list

  • Make sure you've allowed location access in your browser
  • Check browser console for errors
  • Try manually syncing stations using the curl command above
  • Verify your internet connection (needs to reach OpenChargeMap API)

Port Already in Use

Error: "Port 3000 is already in use"

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# Then restart the server

Error: "Port 5000 is already in use"

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# Then restart the server

Development Tips

Useful Commands

# Frontend
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server

# Backend
npm run dev          # Start with nodemon (auto-reload)
npm start            # Start normally
npm run db:setup     # Create database and schema
npm run db:seed      # Seed with sample data

Database Management

# Connect to database
psql -U postgres -d evflow

# View all tables
\dt

# View table structure
\d users
\d charging_stations

# Query examples
SELECT COUNT(*) FROM charging_stations;
SELECT * FROM ev_models;

# Exit
\q

Testing the API

Use tools like Postman, Insomnia, or curl:

# Health check
curl http://localhost:5000/health

# Get nearby stations
curl "http://localhost:5000/api/stations/nearby?latitude=37.7749&longitude=-122.4194&radius=10"

# Register user
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test User",
    "email": "test@example.com",
    "password": "password123"
  }'

Next Steps

  1. Customize Your Profile: Add your EV model in the profile section
  2. Explore Stations: Browse nearby charging stations on the map
  3. Track Battery: Update your battery level for smart recommendations
  4. Log Sessions: Start tracking your charging history
  5. Get Insights: View your charging patterns and preferences

Production Deployment

For production deployment, you'll need to:

  1. Set up a production PostgreSQL database (AWS RDS, Heroku Postgres, etc.)
  2. Deploy backend to a service like Heroku, Railway, or AWS
  3. Deploy frontend to Vercel, Netlify, or similar
  4. Update environment variables for production URLs
  5. Set up proper CORS and security headers
  6. Enable HTTPS
  7. Set up monitoring and logging
  8. Configure rate limiting
  9. Set up automated backups

Need help? Check the README.md for more detailed documentation!