Setup Guide Backend + Frontend

PlanniQ Setup

Complete guide for backend development on EC2 and full local development with GitHub. Choose the workflow that fits your situation.

Option 1: Backend Development on EC2

Info:No npm start needed — edit backend files directly on EC2 and only restart the backend when you make changes.

Edit backend files directly on EC2
Frontend stays as Docker container (already deployed)
Only backend restarts when you make changes
No npm install needed

Step 1: SSH into EC2

Replace <YOUR_EC2_IP> with your actual IP address.

bash

ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>

Step 2: Check Backend Status

bash

# Check if backend is running
docker ps | grep planniq-backend

# View backend logs
docker logs planniq-backend -n 20

Step 3: Stop Backend Container

bash

docker stop planniq-backend

Step 4: Activate Python Virtual Environment

bash

cd ~/planniq/backend
source venv/bin/activate

# You should see (venv) at the start of terminal line

Step 5: Install Dependencies (First Time Only)

bash

pip install -r requirements.txt

Step 6: Run Backend Directly (Not Docker)

bash

python main.py
# or with reload:
uvicorn main:app --reload --host 0.0.0.0 --port 8000

You should see:

output

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Connected to MongoDB

Step 7: Make Changes to Backend Code

In another SSH terminal (or editor):

bash

# New terminal, SSH again:
ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>

# Edit any file
nano ~/planniq/backend/main.py
# Make changes, save (Ctrl+X, Y, Enter)

# Backend auto-reloads! No restart needed

The backend terminal will show:

output

INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application startup complete.

Step 8: Test Backend is Working

bash

curl http://localhost:8000/health
# Should return: {"status":"ok"}

Or test with Postman: GET http://<YOUR_EC2_IP>:8000/health

Step 9: When Done, Restart Docker

bash

# Stop Python backend
Ctrl + C

# Deactivate venv
deactivate

# Restart Docker container
docker start planniq-backend
docker logs planniq-backend

# Verify it's running
docker ps | grep planniq-backend

Common Backend Commands (EC2)

bash

# SSH in
ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>

# Activate venv
cd ~/planniq/backend
source venv/bin/activate

# Run backend
python main.py

# View logs (in another terminal)
tail -f logs/app.log

# Edit file
nano routes/bookings.py

# Test endpoint
curl -X GET http://localhost:8000/api/bookings

# Stop backend
Ctrl + C

# Deactivate
deactivate

EC2: Changing Frontend Code

If you want to update frontend code while working on EC2.

Step 1: SSH and Navigate

bash

ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
cd ~/planniq/frontend

Step 2: Check Frontend Docker Status

bash

docker ps | grep planniq-frontend
# Should see running container

Step 3: Edit Frontend Files

Option A: Using Nano Editor

bash

nano src/pages/Dashboard.jsx
# Make changes
# Save: Ctrl+X, Y, Enter

Option B: Using VS Code Remote SSH

text

Install "Remote - SSH" extension in VS Code
Click Remote icon (bottom left)
Select "Connect to Host"
Enter: ubuntu@<YOUR_EC2_IP>
Open folder: /home/ubuntu/planniq/frontend
Edit files directly in VS Code
Changes auto-save

Step 4: Rebuild Frontend Docker

bash

# Stop current container
docker stop planniq-frontend

# Remove  current container
docker rm planniq-frontend

# Navigate to frontend
cd ~/planniq/frontend

# Rebuild image (takes 2-3 minutes)
docker build -t planniq-frontend:latest .

# Run new container
docker run -d -p 3000:3000 --name planniq-frontend planniq-frontend:latest

# Check logs
docker logs planniq-frontend

# Or use Docker Compose
docker-compose down
docker-compose up -d

Step 5: Test Changes

bash

# Visit in browser:
http://<YOUR_EC2_IP>:3000
# or
https://app.planniq.in

Quick Summary (EC2 Frontend Changes):

bash

ssh -i key.pem ubuntu@<IP>
cd ~/planniq/frontend

nano src/pages/Dashboard.jsx

docker build -t planniq-frontend:latest .
docker restart planniq-frontend

# Test
http://<YOUR_EC2_IP>:3000

Option 2: Full Local Development with GitHub

Install the following on your laptop before starting:

Node.js 16+ — nodejs.org
Python 3.9+ — python.org
Git — git-scm.com
VS Code — code.visualstudio.com

Step 1: Clone Repository from GitHub

bash

# Navigate to where you want the project
cd ~/Documents

# Clone the repo
git clone https://github.com/YOUR_USERNAME/planniq.git
cd planniq

Step 2: Setup Backend Locally

Open Terminal 1 for the backend:

bash

cd ~/Documents/planniq/backend

# Create virtual environment (first time only)
python -m venv venv

# Activate virtual environment
# On Mac/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
nano .env

Paste this in .env:

.env

MONGODB_URL=mongodb+srv://planniq_admin:PASSWORD@planniq-cluster.xxxxx.mongodb.net/planniq_db
JWT_SECRET_KEY=your-secret-key-here-min-32-chars
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440
API_TITLE=PlanniQ API
API_VERSION=1.0.0
DEBUG=true
ALLOWED_ORIGINS=["http://localhost:3000"]

Save with Ctrl+X, Y, Enter. Then run the backend:

bash

python main.py
# or with auto-reload:
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Step 3: Setup Frontend Locally

Open Terminal 2 for the frontend:

bash

cd ~/Documents/planniq/frontend

# Install dependencies
npm install --legacy-peer-deps

# Create .env file
nano .env

Paste this in .env:

.env

REACT_APP_API_URL=http://localhost:8000
REACT_APP_ENV=development

bash

npm start

Tip:Should open http://localhost:3000 automatically.

Step 4: Test Everything Works

bash

# Browser
http://localhost:3000
# Should see login page

# Test backend (Terminal 3)
curl http://localhost:8000/health
# Should return: {"status":"ok"}

# API Docs
http://localhost:8000/docs
# Should show Swagger UI

Step 5: Making Changes (Daily Workflow)

Edit Backend Files:

bash

# Edit ~/planniq/backend/routes/bookings.py
# Save file → Backend auto-reloads! ⚡
curl -X GET http://localhost:8000/api/bookings

Edit Frontend Files:

bash

# Edit ~/planniq/frontend/src/pages/Dashboard.jsx
# Save file → Browser auto-refreshes! ⚡

Step 6: Commit Changes to GitHub

bash

cd ~/Documents/planniq

git status
git add .
git commit -m "feat: add new booking feature"
git push origin main

Step 7: Create Feature Branch (Team Workflow)

bash

cd ~/Documents/planniq

git checkout -b feature/new-feature

# Make changes & test
git add .
git commit -m "feat: add calendar view"
git push origin feature/new-feature

# Go to GitHub → Create Pull Request
# Get review, merge to main

Step 8: Pull Latest Changes from GitHub

bash

cd ~/Documents/planniq
git pull origin main

# If backend changed:
cd backend
pip install -r requirements.txt  # Install new dependencies

# If frontend changed:
cd ../frontend
npm install                      # Install new dependencies

Comparison: Option 1 vs Option 2

Task	Option 1 (EC2)	Option 2 (Local)
Edit backend	SSH into EC2, nano editor	VS Code locally
Hot reload	Auto-restart	Auto-reload ⚡
Edit frontend	Docker (no changes)	npm start (hot reload) ⚡
Test changes	Instant	Instant ⚡
Commit code	Git on EC2	Git locally
Performance	Slow (low memory)	Fast ✅
When to use	Quick backend fixes	Active development

Recommended Workflow

Daily Development:

text

1. Use Option 2 (Local)
   - npm start (frontend)
   - python main.py (backend)
   - Make changes, test
   - Commit & push to GitHub

2. Once per day
   - Pull latest from GitHub on EC2
   - Rebuild Docker images
   - Test on production URL

Quick Backend Fix on Production:

text

SSH to EC2
Stop Docker
Run Option 1 (EC2 direct Python)
Make quick fix
Restart Docker

GitHub Scenarios

Scenario 1: Update Just Frontend Code

Make Changes Locally

bash

cd ~/Documents/planniq/frontend
# Edit src/pages/Dashboard.jsx → browser auto-refreshes ⚡

Commit to GitHub

bash

cd ~/Documents/planniq
git status
git add frontend/
git commit -m "feat: update dashboard layout"
git push origin main

Update EC2

bash

ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
cd ~/planniq
git pull origin main
cd frontend
docker build -t planniq-frontend:latest .
docker restart planniq-frontend
docker logs planniq-frontend

Scenario 2: Update Just Backend Code

bash

# Locally - edit routes/bookings.py → backend auto-reloads ⚡
curl -X GET http://localhost:8000/api/bookings

# Commit
cd ~/Documents/planniq
git add backend/
git commit -m "fix: improve booking validation"
git push origin main

# Update EC2
ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
cd ~/planniq && git pull origin main
cd backend && pip install -r requirements.txt
docker build -t planniq-backend:latest .
docker restart planniq-backend

Scenario 3: Update Both Frontend & Backend

bash

# Terminal 1: cd frontend && npm start
# Terminal 2: cd ../backend && python main.py
# Edit both files → both auto-reload ⚡

git add .
git commit -m "feat: add new booking workflow (frontend + backend)"
git push origin main

# EC2
ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
cd ~/planniq && git pull origin main
cd backend && pip install -r requirements.txt && docker build -t planniq-backend:latest .
cd ../frontend && docker build -t planniq-frontend:latest .
docker-compose down && docker-compose up -d
docker ps

Scenario 4: Add New Package/Dependency

Frontend package:

bash

npm install axios
git add package.json package-lock.json
git commit -m "feat: add axios for API calls"
git push origin main

Backend package:

bash

pip install fastapi-cors
pip freeze > requirements.txt
git add requirements.txt
git commit -m "feat: add CORS support"
git push origin main

Scenario 5: Quick Hotfix (Skip Local Testing)

Note:Emergency fix needed on production? Choose one of these approaches.

Option A: Direct EC2 Edit (Fast)

bash

ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
docker stop planniq-backend
cd ~/planniq/backend && source venv/bin/activate
nano routes/bookings.py  # Make fix
python main.py  # Ctrl+C after testing
docker start planniq-backend
git add routes/bookings.py
git commit -m "hotfix: fix booking error"
git push origin main

Option B: Local → GitHub → EC2 (Better)

bash

# Locally
git add . && git commit -m "hotfix: urgent fix" && git push origin main
# On EC2
cd ~/planniq/backend && git pull origin main
docker build -t planniq-backend:latest . && docker restart planniq-backend

Scenario 6: Pull Latest Changes from Team

bash

cd ~/Documents/planniq
git fetch origin && git status  # Check if behind
git pull origin main

# If backend changed:
cd backend && pip install -r requirements.txt

# If frontend changed:
cd ../frontend && npm install

# Both at once:
pip install -r backend/requirements.txt
npm install --prefix frontend

Scenario 7: Work on Feature Branch (Team Workflow)

bash

git checkout -b feature/calendar-view
# Edit, test with npm start...
git add frontend/
git commit -m "feat: add calendar booking view"
git push origin feature/calendar-view
# → GitHub: Create Pull Request → Approve → Merge

# After merge:
git checkout main && git pull origin main
git branch -d feature/calendar-view
git push origin --delete feature/calendar-view

# EC2:
ssh -i planniq-key.pem ubuntu@<YOUR_EC2_IP>
cd ~/planniq && git pull origin main
cd frontend && docker build -t planniq-frontend:latest .
cd ../backend && docker build -t planniq-backend:latest .
docker-compose restart

Scenario 8: Revert Changes (Undo Last Commit)

bash

git log --oneline        # See history
git revert HEAD          # Revert last commit (safe)
# or: git reset --soft HEAD~1  (careful! loses history)
git add . && git commit -m "fix: proper version"
git push origin main

# EC2:
cd ~/planniq && git revert HEAD
docker-compose down && docker-compose up -d

Scenario 9: Merge Conflict (Multiple People Editing)

bash

git pull origin main   # Error: merge conflict!

nano backend/main.py
# Look for and resolve:
# <<<<<<< HEAD
# your changes
# =======
# their changes
# >>>>>>> main

git add .
git commit -m "resolve: merge conflict"
git push origin main

Quick Reference Table

Task	Command
Update Frontend Only	`git add frontend/ → commit → push → EC2: rebuild frontend Docker`
Update Backend Only	`git add backend/ → commit → push → EC2: rebuild backend Docker`
Update Everything	`git add . → commit → push → EC2: rebuild all`
Add Frontend Package	`npm install X → git add package.json → commit → push`
Add Backend Package	`pip install X → pip freeze > requirements.txt → commit → push`
Pull Latest	`git pull origin main → reinstall deps → restart`
New Feature	`git checkout -b feature/X → edit → commit → push → PR`
Quick Hotfix	`Edit EC2 directly OR fast local commit`
Undo Last	`git revert HEAD → commit → push`
View History	`git log --oneline`

Useful Commands

Local Development (Option 2):

bash

# Frontend
npm start              # Start with hot reload
npm test              # Run tests
npm run build         # Build for production
npm install package   # Add new package

# Backend
python main.py                    # Run
uvicorn main:app --reload        # Run with reload
pytest                           # Run tests
pip install -r requirements.txt  # Install dependencies

# Git
git status            # Check changes
git add .             # Stage changes
git commit -m "msg"   # Commit
git push              # Push to GitHub
git pull              # Get latest
git checkout -b name  # Create branch

EC2 Development (Option 1):

bash

ssh -i key.pem ubuntu@<IP>       # SSH in
cd ~/planniq/backend               # Navigate
source venv/bin/activate           # Activate venv
python main.py                     # Run backend
deactivate                         # Exit venv

docker ps                          # List containers
docker logs planniq-backend -f     # Follow logs
docker restart planniq-backend     # Restart
docker stop planniq-backend        # Stop
docker start planniq-backend       # Start

nano file.py         # Edit file
# Ctrl+X, Y, Enter  # Save

Troubleshooting

Local Development Issues

Port 3000 in use:

bash

lsof -ti:3000 | xargs kill -9
npm start

Port 8000 in use:

bash

lsof -ti:8000 | xargs kill -9
python main.py

Modules not found:

bash

# Frontend
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

# Backend
pip install -r requirements.txt

Changes not reflecting:

text

Frontend: Ctrl+Shift+R (Win/Linux) or Cmd+Shift+R (Mac)
Backend: Check terminal for errors — make sure uvicorn is running with --reload

EC2 Issues

Backend won't start:

bash

docker logs planniq-backend
# Check .env file and MongoDB connection

Out of memory:

bash

docker stop planniq-backend
sync && echo 3 > /proc/sys/vm/drop_caches
docker start planniq-backend

Checklists

Option 1 Setup Checklist (EC2 Backend)

SSH into EC2

Stop Docker container

Activate Python venv

Install pip requirements

Create .env file with MongoDB URL

Run python main.py

Test with curl or Postman

Make changes in nano/VS Code

Backend auto-reloads

Restart Docker when done

Option 2 Setup Checklist (Local GitHub)

Install Node.js, Python, Git

Clone repo from GitHub

Setup backend venv & dependencies

Setup frontend npm install

Create .env files

Run python main.py (Terminal 1)

Run npm start (Terminal 2)

Test at localhost:3000 & localhost:8000

Make changes & see them reflect live

Commit & push to GitHub

Ready to develop! 🚀

Next Steps

Tip:Start with Option 2 (Local) — it's faster and better for active development.

Use Option 1 (EC2) only for:

Quick hotfixes in production
Testing on production domain
Debugging specific server issues

Good luck! 🚀