firefly_reports/RUN_APP.md

🚀 How to Run the Firefly III Analytics App

Quick Start (3 Steps)

Step 1: Set Up Environment Variables

Create/edit .env file in the project root:

FIREFLY_URL=https://firefly.scsimedia.duckdns.org
FIREFLY_API_TOKEN=your_api_token_from_firefly_iii
DATABASE_URL=sqlite:///./data/app.db
SYNC_INTERVAL_MINUTES=30

Step 2: Start Backend (Terminal 1)

cd backend
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

You should see:

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

Step 3: Start Frontend (Terminal 2)

cd frontend
npm start

Browser will auto-open at http://localhost:3000

---

✅ Verify It's Running

• Backend API: http://localhost:8000
• Health check: http://localhost:8000/health (should return {"status": "healthy"})
• Frontend: http://localhost:3000

---

🐳 Option 2: Using Docker Compose (Easier)

If you have Docker installed:

# From project root
docker-compose up --build

This starts:

• Backend on http://localhost:8000
• Frontend on http://localhost:3000
• SQLite database at ./data/app.db

Stop with: Ctrl+C

---

🔧 Troubleshooting

Backend won't start - "ModuleNotFoundError: No module named 'app'"

cd backend
python -m uvicorn app.main:app --reload

Make sure you're IN the backend folder when running the command.

"Address already in use" on port 8000

Change the port:

python -m uvicorn app.main:app --reload --port 8001

Frontend won't start - "npm not found"

Install Node.js from https://nodejs.org (includes npm)

"FIREFLY_API_TOKEN not set"

Make sure .env file exists in the project root with your token.

---

📋 What Happens When You Start

1. Backend initializes:

   • Connects to SQLite database
   • Creates tables if needed
   • Starts sync scheduler (runs every 30 min)
   • Starts FastAPI server

2. Frontend starts:

   • React dev server starts
   • Browser opens to http://localhost:3000
   • Dashboard loads with data from backend

3. Data Sync:

   • Background job fetches from Firefly III every 30 minutes
   • Data cached locally in SQLite
   • API endpoints return cached data

---

🎯 Default Ports

Service	Port	URL
Backend	8000	http://localhost:8000
Frontend	3000	http://localhost:3000
Database	-	./data/app.db (SQLite file)

---

💡 Development Tips

Run Backend with Hot Reload

cd backend
python -m uvicorn app.main:app --reload

Run Frontend with Hot Reload

cd frontend
npm start

View API Documentation

Open: http://localhost:8000/docs (Swagger UI)

Clear Database and Restart

# Stop the servers (Ctrl+C)
rm data/app.db
# Restart - it will recreate the database

---

🔒 Security Notes

• Never commit .env to git (it's in .gitignore)
• Keep your Firefly III API token secret
• In production, use environment variables, not .env files
• See ARCHITECTURE.md for production deployment guide

---

Your app is now running! 🎉

Go to http://localhost:3000 and start viewing your financial analytics.