Skip to main content
This guide walks you through setting up the Fantasy Basketball Analytics application on your local development environment.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.x - The application is built with Flask and requires Python 3.7 or higher
  • pip - Python package installer (usually comes with Python)
  • ngrok - Required for OAuth callback handling during local development
You must use ngrok for local development because Yahoo OAuth requires HTTPS callbacks, which localhost cannot provide.

​
Yahoo Developer Account Setup

1

Create Yahoo Developer Application

Visit the Yahoo Developer Network and create a new application:
  • Select Fantasy Sports API access
  • Choose Read permissions (required for fetching league data)
  • Note your Client ID and Client Secret - you’ll need these later
2

Install ngrok

Download and install ngrok from ngrok.com:
# macOS (using Homebrew)
brew install ngrok

# Windows (using Chocolatey)
choco install ngrok

# Or download directly from ngrok.com
3

Clone the Repository

Clone the Fantasy Basketball Analytics repository:
git clone https://github.com/AlexIbby/fantasyBasketball.git
cd fantasyBasketball
4

Install Python Dependencies

Install all required packages from requirements.txt:
pip install -r requirements.txt
Consider using a virtual environment to isolate dependencies:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
5

Configure Environment Variables

Create a .env file in the project root directory:
# Copy the example file
cp .env.example .env
Edit .env with your configuration:
YAHOO_CLIENT_ID=your_yahoo_client_id
YAHOO_CLIENT_SECRET=your_yahoo_client_secret
FLASK_SECRET_KEY=your_random_secret_key_here
FLASK_ENV=development
See Environment Variables for detailed explanations.
6

Start ngrok Tunnel

In a separate terminal window, start ngrok to tunnel to port 5000:
ngrok http 5000
You’ll see output like:
Forwarding  https://abc123def456.ngrok.io -> http://localhost:5000
Copy the HTTPS URL (e.g., https://abc123def456.ngrok.io) - you’ll need this for the next step.
Keep the ngrok terminal running while you develop. If you restart ngrok, you’ll get a new URL and need to update your Yahoo app settings.
7

Update Yahoo App Redirect URI

Go back to your Yahoo Developer application settings and update:
  • Redirect URI: https://your-ngrok-url.ngrok.io/callback
Replace your-ngrok-url with your actual ngrok domain.
8

Run the Application

Start the Flask development server:
python main.py
The application will start in debug mode on port 5000:
# From main.py:971
if __name__ == "__main__":
    app.run(debug=True, port=5000, host='0.0.0.0')
9

Access the Application

Open your ngrok HTTPS URL in a web browser (not localhost:5000):
https://abc123def456.ngrok.io
You should see the login page. Click “Login with Yahoo” to authenticate.

​
Development Features

When running with FLASK_ENV=development, the application automatically:
  • Loads environment variables from .env file using python-dotenv
  • Enables Flask debug mode for auto-reload on code changes
  • Provides detailed error messages and stack traces
  • Logs informational messages to help with debugging
# From main.py:18-24
if os.getenv("FLASK_ENV", "development") == "development":
    try:
        from dotenv import load_dotenv, dotenv_values
        load_dotenv()
        _ = dotenv_values()
    except Exception as e:
        logging.warning("[dotenv] %s – check .env formatting (KEY=VALUE).", e)

​
Debug Endpoints

The application includes helpful debug endpoints for development:
EndpointDescription
/debug/league_settingsView raw league settings JSON
/debug/scoreboard?week=1View raw scoreboard data for a specific week
Use these endpoints to inspect the Yahoo API responses and understand the data structure.

​
Troubleshooting

  • Verify your ngrok URL matches exactly in Yahoo app settings
  • Ensure you’re accessing via the HTTPS ngrok URL, not localhost
  • Check that ngrok is still running in the background
  • Ensure all dependencies are installed: pip install -r requirements.txt
  • Check you’re using Python 3.7 or higher: python --version
  • Activate your virtual environment if using one
  • Verify .env file is in the project root directory
  • Check file formatting (no quotes around values unless needed)
  • Ensure FLASK_ENV=development is set to trigger dotenv loading
  • Verify your Client ID and Secret are correct
  • Check that the Yahoo app has Fantasy Sports API permissions
  • Ensure the redirect URI in Yahoo settings exactly matches your ngrok URL + /callback

​
Next Steps

Environment Variables

Learn about all configuration options

Heroku Deployment

Deploy your app to production

Build docs developers (and LLMs) love

Get started for freeTalk to us