snippet-pastebin/docs/QUICKSTART.md

Quick Start Guide

Choose Your Setup

🚀 Full Stack with Docker (Easiest)

Everything runs in Docker with automatic backend configuration.

docker-compose up -d

✅ Frontend: http://localhost:3000
✅ Backend: http://localhost:5000
✅ Auto-configured to use Flask backend

---

💻 Local Development

Backend in Docker, frontend in development mode.

# Terminal 1: Start backend
docker-compose -f docker-compose.backend-only.yml up -d

# Terminal 2: Configure and start frontend
echo "VITE_FLASK_BACKEND_URL=http://localhost:5000" > .env
npm install
npm run dev

✅ Frontend: http://localhost:5173 (Vite dev server)
✅ Backend: http://localhost:5000
✅ Auto-configured to use Flask backend

---

🌐 Frontend Only (Local Storage)

No backend required - uses browser IndexedDB.

npm install
npm run dev

✅ Frontend: http://localhost:5173
✅ Data stored locally in browser
✅ No server needed

---

⚙️ Backend Only

Run backend separately, configure frontend manually.

cd backend
pip install -r requirements.txt
python app.py

Then in a separate terminal:

npm install
npm run dev

✅ Backend: http://localhost:5000
✅ Frontend: http://localhost:5173
⚠️ Must configure backend URL in Settings page

---

Key Features by Setup

Feature	Full Stack Docker	Local Dev	Frontend Only	Backend Only
Auto-configured backend	✅	✅	❌	❌
Hot reload	❌	✅	✅	✅
Multi-device sync	✅	✅	❌	✅*
No dependencies	❌	❌	✅	❌
Production-ready	✅	❌	❌	⚠️

*Requires manual configuration

---

Environment Variables

VITE_FLASK_BACKEND_URL

What it does:
Automatically configures the app to use a Flask backend instead of IndexedDB.

When set:

• App connects to Flask backend on startup
• Settings page backend selection is disabled
• Overrides any manual configuration

Examples:

Local backend:

VITE_FLASK_BACKEND_URL=http://localhost:5000

Docker internal:

VITE_FLASK_BACKEND_URL=http://backend:5000

Remote backend:

VITE_FLASK_BACKEND_URL=https://api.example.com

Setup methods:

.env file:

echo "VITE_FLASK_BACKEND_URL=http://localhost:5000" > .env

Docker Compose:

services:
  frontend:
    environment:
      - VITE_FLASK_BACKEND_URL=http://backend:5000

Docker build:

docker build --build-arg VITE_FLASK_BACKEND_URL=http://api.example.com .

---

Common Commands

Docker

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f

# Rebuild after code changes
docker-compose up -d --build

# Start backend only
docker-compose -f docker-compose.backend-only.yml up -d

NPM

# Install dependencies
npm install

# Development server
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

Backend (Python)

cd backend

# Install dependencies
pip install -r requirements.txt

# Run server
python app.py

# Run with custom database path
DB_PATH=/custom/path/snippets.db python app.py

---

Troubleshooting

"Connection failed" in Settings

Problem: Can't connect to Flask backend

Solutions:

1. Verify backend is running: curl http://localhost:5000/health
2. Check URL is correct (include http://)
3. Ensure no firewall is blocking port 5000
4. Check backend logs: docker-compose logs backend

Environment variable not working

Problem: VITE_FLASK_BACKEND_URL not taking effect

Solutions:

1. Restart dev server after creating/modifying .env
2. Ensure file is named .env (not .env.txt)
3. Variable must start with VITE_
4. For production builds: rebuild with npm run build

Settings page is read-only

This is expected when VITE_FLASK_BACKEND_URL is set.

To enable manual configuration:

1. Remove the variable from .env
2. Restart the application

Port already in use

Problem: "Port 3000 (or 5000) is already in use"

Solutions:

Change frontend port:

# docker-compose.yml
services:
  frontend:
    ports:
      - "8080:3000"  # Access at http://localhost:8080

Change backend port:

# docker-compose.yml
services:
  backend:
    ports:
      - "8000:5000"  # Access at http://localhost:8000
    environment:
      - VITE_FLASK_BACKEND_URL=http://backend:5000  # Keep internal port same

Or stop the conflicting service:

# Find process using port
lsof -i :3000

# Kill process (replace PID)
kill -9 <PID>

---

Next Steps

• 📖 Full documentation
• 🔧 Backend configuration guide
• 🐳 Docker examples
• 🚀 Backend API docs