153 lines
3.3 KiB
Markdown
153 lines
3.3 KiB
Markdown
# 🚀 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)
|
|
```bash
|
|
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)
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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'"
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
```bash
|
|
cd backend
|
|
python -m uvicorn app.main:app --reload
|
|
```
|
|
|
|
### Run Frontend with Hot Reload
|
|
```bash
|
|
cd frontend
|
|
npm start
|
|
```
|
|
|
|
### View API Documentation
|
|
Open: http://localhost:8000/docs (Swagger UI)
|
|
|
|
### Clear Database and Restart
|
|
```bash
|
|
# 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.
|