🏈 FantasyPulse

A self-hosted fantasy football dashboard with real-time scoring, play-by-play updates, historical stats, and Yahoo Fantasy integration.

FantasyPulse - Feel every satisfying point in real-time.

✨ Features

• Real-time Scoring - Live updates during NFL games via WebSocket
• Play-by-Play Tracking - See every scoring play matched to your fantasy players
• All League Matchups - View every matchup in your league, not just yours
• Historical Data - Track your league's history across multiple seasons
• Owner Statistics - Comprehensive stats and head-to-head records
• Responsive Design - Works on desktop, tablet, and mobile
• Dark Mode - Easy on the eyes for those late Sunday night games

---

🚀 Quick Start

Option 1: One-Command Install (Recommended)

No need to clone the repo! Just download the docker-compose file and run:

# Download the docker-compose file
curl -O https://raw.githubusercontent.com/dnielso5/fantasypulse/main/docker-compose.hub.yml

# Rename it
mv docker-compose.hub.yml docker-compose.yml

# Run it
docker-compose up -d

Then open http://localhost:8888/setup/ to configure your Yahoo credentials.

Option 2: Clone and Build

If you want to customize the code or contribute:

# Clone the repository
git clone https://github.com/dnielso5/fantasypulse.git
cd fantasypulse

# Build and run
docker-compose up -d --build

---

🔧 First-Time Setup

After starting the container, complete the setup wizard:

1. Open http://localhost:8888/setup/
2. Enter your Yahoo API credentials (see below)
3. Enter your League ID
4. Click "Test Connection"
5. Done! Visit http://localhost:8888

---

🔑 Getting Yahoo API Credentials

Step 1: Create a Yahoo App

1. Go to Yahoo Developer Portal
2. Click "Create an App"
3. Fill in the form:
   • Application Name: FantasyPulse (or any name)
   • Application Type: Web Application
   • Redirect URI: https://localhost
   • API Permissions: Check "Fantasy Sports"
4. Click "Create App"

Step 2: Get Your Credentials

After creating the app, you'll see:

• Client ID (Consumer Key) - Copy this
• Client Secret (Consumer Secret) - Copy this

Step 3: Find Your League ID

Your League ID is in your Yahoo Fantasy URL:

https://football.fantasysports.yahoo.com/f1/XXXXXX
                                          ^^^^^^
                                          This is your League ID

---

📁 Project Structure

fantasypulse/
├── api/                    # PHP API endpoints
├── assets/                 # CSS, JavaScript
├── classes/                # PHP classes
├── config/                 # Configuration files
├── data/                   # League data (auto-populated)
├── docker/                 # Docker configuration
├── pages/                  # Dashboard pages
├── setup/                  # First-run setup wizard
├── yfpy/                   # Yahoo Fantasy Python library
├── docker-compose.yml      # Local build version
├── docker-compose.hub.yml  # Pre-built image version
├── Dockerfile              # Container build instructions
├── scheduler.py            # Background data fetcher
└── websocket-server.js     # Real-time updates server

---

⚙️ Configuration

Environment Variables

Variable	Description	Default
WEB_PORT	Web interface port	8888
WEBSOCKET_PORT	WebSocket port	8080
TZ	Timezone	America/Los_Angeles

Custom Ports

To use different ports, create a .env file:

WEB_PORT=9000
WEBSOCKET_PORT=9001
TZ=America/New_York

---

🔄 Updating

If using pre-built image:

docker-compose pull
docker-compose up -d

If using local build:

git pull
docker-compose up -d --build

---

🐛 Troubleshooting

Container won't start

docker-compose logs -f

No data showing

1. Verify Yahoo credentials at /setup/
2. Check if it's currently game time (data fetches during games)
3. View logs: docker-compose logs fantasypulse

Permission errors

docker-compose exec fantasypulse chown -R www-data:www-data /var/www/html/data

Reset everything

docker-compose down -v
docker-compose up -d

---

📊 Importing Historical Data

If you have historical league data from previous seasons:

1. Place JSON files in data/YEAR/week_X/ folders
2. Follow naming convention: weekXmatchupsYEAR.json
3. See data/DATA_STRUCTURE.md for format details

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

📜 License

MIT License - feel free to use this for your own fantasy leagues!

---

🙏 Acknowledgments

• YFPY - Yahoo Fantasy Sports API wrapper
• ESPN API - Play-by-play data
• Chart.js - Beautiful charts

---

FantasyPulse - Made with ❤️ for fantasy football enthusiasts