🚀 LocateTheNews Startup Guide

Quick Start

Backend (FastAPI)

macOS/Linux:

cd backend
./start.sh

or manually:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m spacy download en_core_web_sm
python -m app.main

Windows:

cd backend
start.bat

or manually:

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python -m spacy download en_core_web_sm
python -m app.main

Backend will be running at http://localhost:8000.

API Documentation: http://localhost:8000/api/docs

---

Frontend (React)

Open a new terminal:

cd frontend
npm install
npm start

Frontend will automatically open at http://localhost:3000.

---

Step-by-Step Detailed Setup

1. Backend Setup

Requirements:

• Python 3.8+
• pip

Steps:

1. Go to backend directory:

   cd backend
   

2. Create virtual environment:

   python3 -m venv venv
   # Windows: python -m venv venv
   

3. Activate virtual environment:

   source venv/bin/activate
   # Windows: venv\Scripts\activate
   

4. Install packages:

   pip install -r requirements.txt
   

5. Download spaCy model (for NLP):

   python -m spacy download en_core_web_sm
   

   For Turkish (optional):

   python -m spacy download tr_core_news_sm
   

6. Start Backend:

   python -m app.main
   

   Or with uvicorn:

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

✅ If the backend is running successfully, you will see:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

---

2. Frontend Setup

Requirements:

• Node.js 16+
• npm or yarn

Steps:

1. Go to frontend directory:

   cd frontend
   

2. Install packages:

   npm install
   

3. Start Frontend:

   npm start
   

✅ If the frontend is running successfully, your browser will open automatically:

Compiled successfully!
You can now view locatethenews-frontend in the browser.
  Local:            http://localhost:3000

---

Testing

Backend Test:

1. Open in browser: http://localhost:8000/api/docs
2. You can test endpoints in Swagger UI
3. Health check: http://localhost:8000/api/v1/health
4. Events: http://localhost:8000/api/v1/events

Frontend Test:

1. Open in browser: http://localhost:3000
2. You should see news markers on the map
3. Click on markers to see news details

---

Troubleshooting

Backend issues:

Import error:

# Check if virtual environment is active
which python  # macOS/Linux
where python  # Windows
# Should point to venv/bin/python or venv\Scripts\python

spaCy model error:

python -m spacy download en_core_web_sm

Port already in use:

# Find and kill the process using port 8000
lsof -ti:8000 | xargs kill  # macOS/Linux
# or change SERVER_PORT in config.py

Frontend issues:

npm install error:

# Check Node.js version
node --version  # should be 16+

# Clean npm cache
npm cache clean --force
npm install

Port 3000 in use:

# Use a different port
PORT=3001 npm start

Backend connection error:

• Ensure backend is running (http://localhost:8000/api/v1/health)
• Check CORS settings (backend/app/config.py)

---

Production Build

Frontend Build:

cd frontend
npm run build
# Static files will be generated in build/ folder

Backend Production:

# With Gunicorn (recommended)
pip install gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

---

Running with Docker (Future)

docker-compose up

---

Help

If you encounter issues:

1. Check terminal outputs
2. Review log files
3. Ensure ports are open
4. Verify that the virtual environment is active