Installation Guide

This guide provides comprehensive instructions for installing and configuring OddsEngine on your system.

System Requirements

Hardware Requirements

CPU: 2+ cores recommended (4+ for optimal performance)
RAM: Minimum 4GB (8GB+ recommended for large datasets)
Storage: At least 2GB free disk space
Network: Internet connection for API data fetching

Operating System Support

Linux

Ubuntu 20.04+, Debian 11+, Fedora 35+, or compatible distributions

macOS

macOS 11 (Big Sur) or later with Homebrew

Windows

Windows 10/11 with WSL2 recommended for Docker

Prerequisites

1. Docker and Docker Compose

Docker is required to run the Oracle Database container.

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Verify installation
docker --version
docker compose version

On Windows, ensure WSL2 is properly configured. Docker Desktop requires WSL2 backend for optimal performance.

2. Python 3.10 or Higher

OddsEngine requires Python 3.10+ for compatibility with modern libraries.

# Check current version
python3 --version

# If Python 3.10+ is not installed:
sudo apt-get update
sudo apt-get install python3.10 python3.10-venv python3-pip

# Set as default (optional)
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1

3. Git

Required for cloning the repository.

sudo apt-get install git
git --version

Installing OddsEngine

Clone the Repository

Clone the OddsEngine repository from GitHub:

git clone https://github.com/puj-course/FIS_2610_3517_G2.git
cd FIS_2610_3517_G2

Verify the project structure:

ls -la

You should see directories like src/, conf/, docker-compose.yml, etc.

Create Python Virtual Environment

Create an isolated Python environment for OddsEngine:

python3 -m venv venv

Activate the virtual environment:

source venv/bin/activate

Your prompt should now show (venv) prefix.

Install Python Dependencies

Install all required Python packages:

pip install --upgrade pip
pip install -r requirements.txt

Key dependencies being installed:

PyQt6: Desktop GUI framework
pandas: Data analysis and statistical calculations
httpx: Async HTTP client for API-Tennis integration
oracledb: Oracle Database driver
python-dotenv: Environment variable management

Installation may take 3-5 minutes depending on your connection speed.

Install PyQt System Dependencies

PyQt requires additional system libraries:

sudo apt-get install -y \
  python3-pyqt6 \
  libxcb-xinerama0 \
  libxcb-icccm4 \
  libxcb-image0 \
  libxcb-keysyms1 \
  libxcb-randr0 \
  libxcb-render-util0 \
  libxcb-xfixes0 \
  libxkbcommon-x11-0

Configure Environment Variables

Create a .env file in the project root:

touch .env

Add the following configuration (use your preferred text editor):

# API-Tennis Configuration
API_TENNIS_KEY=your_api_key_here
API_TENNIS_BASE_URL=https://api-tennis.com/v1
API_TENNIS_RATE_LIMIT=1000

# Oracle Database Configuration
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE=XEPDB1
ORACLE_USER=oddsengine
ORACLE_PASSWORD=SecureP@ssw0rd2026
ORACLE_DSN=localhost:1521/XEPDB1

# Application Configuration
APP_ENV=development
LOG_LEVEL=INFO
LOG_FILE=temp/application.log

# Mock Data Fallback
ENABLE_MOCK_FALLBACK=true
MOCK_DATA_PATH=jupyter/datasets/

API Key Required: Sign up for a free API key at api-tennis.com. The free tier provides 1,000 requests per month.

The .env file is automatically ignored by Git (see .gitignore). Never commit sensitive credentials.

Set Up Oracle Database with Docker

Start the Oracle Database container:

docker-compose up -d db

Monitor the initialization process:

docker-compose logs -f db

Wait for the message:

#########################
DATABASE IS READY TO USE!
#########################

This typically takes 2-3 minutes on first run as the database is initialized.

Oracle Database requires at least 4GB of RAM. Ensure Docker Desktop has sufficient memory allocated in Settings → Resources → Memory.

Initialize Database Schema

Run the setup script to create tables and initial data:

chmod +x scripts/setup.sh
./scripts/setup.sh

Or on Windows:

python scripts/setup.py

This script will:

Create player tables
Create match history tables
Create probability calculation tables
Create indexes for performance
Insert seed data for testing

Expected output:

✓ Connected to Oracle Database
✓ Created players table
✓ Created matches table
✓ Created probabilities table
✓ Created indexes
✓ Inserted seed data (25 players, 100 matches)
✓ Database initialization complete

Verify Installation

Run the verification script to check all components:

python scripts/verify_installation.py

This will test:

Python version (3.10+)
Required packages (PyQt6, pandas, etc.)
Database connectivity
API-Tennis connection
File system permissions

All checks should pass with green checkmarks.

Running OddsEngine

After successful installation, launch the application:

# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Start the application
python src/main/python/app.py

The PyQt desktop interface will launch showing the main dashboard.

Project Structure

Understanding the OddsEngine directory layout:

OddsEngine/
├── .github/              # GitHub workflows for CI/CD
│   ├── workflows/
│   │   ├── ci.yml       # Continuous Integration
│   │   └── cd.yml       # Continuous Deployment
├── conf/                 # Configuration files
│   ├── config.yaml      # Application config
│   └── settings.json    # User preferences
├── docs/                 # Project documentation
├── jupyter/              # Data analysis notebooks
│   ├── notebooks/       # Jupyter notebooks
│   └── datasets/        # CSV data files
├── scripts/              # Utility scripts
│   ├── setup.sh         # Database initialization
│   ├── deploy.sh        # Deployment script
│   └── test.sh          # Test runner
├── src/
│   ├── main/python/     # Application source code
│   │   ├── app.py       # Main entry point
│   │   ├── models/      # Probability models
│   │   ├── api/         # API-Tennis client
│   │   └── ui/          # PyQt interface
│   └── test/python/     # Unit and integration tests
├── temp/                 # Temporary files and logs
├── .env                  # Environment variables (create this)
├── .gitignore           # Git ignore rules
├── docker-compose.yml   # Docker services config
├── Dockerfile           # Application container
├── requirements.txt     # Python dependencies
└── README.md            # Project overview

Configuration Files

config.yaml

Application configuration in conf/config.yaml:

api:
  tennis:
    timeout: 30
    retry_attempts: 3
    cache_ttl: 3600

database:
  pool_size: 5
  pool_recycle: 3600
  echo: false

models:
  probability:
    confidence_threshold: 0.7
    min_data_points: 10

ui:
  theme: light
  refresh_interval: 60

settings.json

User preferences in conf/settings.json:

{
  "display": {
    "language": "en",
    "decimal_places": 2,
    "date_format": "YYYY-MM-DD"
  },
  "notifications": {
    "enabled": true,
    "sound": false
  },
  "data_sync": {
    "auto_sync": true,
    "sync_interval_hours": 24
  }
}

Verification Steps

After installation, verify each component:

Check Docker Services

docker-compose ps

Expected output:

NAME                COMMAND                  STATUS              PORTS
oddsengine-db-1     "/bin/sh -c 'exec..."   Up 5 minutes        0.0.0.0:1521->1521/tcp

Test Database Connection

python -c "from src.main.python.db import test_connection; test_connection()"

Should output: ✓ Database connection successful

Test API Connection

python -c "from src.main.python.api import test_api; test_api()"

Should output: ✓ API-Tennis connection successful (1000 requests remaining)

Run Unit Tests

chmod +x scripts/test.sh
./scripts/test.sh

Or directly:

pytest src/test/python/ -v

Troubleshooting

Docker Issues

Docker daemon not running:

# Linux
sudo systemctl start docker

# macOS/Windows
# Start Docker Desktop application

Port 1521 already in use:

# Find process using port
sudo lsof -i :1521  # Linux/macOS
netstat -ano | findstr :1521  # Windows

# Change port in docker-compose.yml and .env

Python Issues

PyQt6 import errors:

# Reinstall PyQt6
pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6

# Linux: Install system dependencies (see Step 4)

oracledb connection fails:

# Check if Oracle container is running
docker-compose logs db

# Verify credentials in .env match docker-compose.yml
# Wait for database to fully initialize (2-3 minutes)

API Issues

API-Tennis rate limit exceeded:

OddsEngine automatically switches to mock data mode
Check remaining requests: curl -H "Authorization: Bearer YOUR_KEY" https://api-tennis.com/v1/status
Rate limits reset monthly

API key invalid:

Verify key in .env file has no extra spaces
Regenerate key at api-tennis.com
Check API service status

Permission Issues

Scripts not executable:

chmod +x scripts/*.sh

Database file permissions:

sudo chown -R $USER:$USER temp/
chmod -R 755 temp/

Updating OddsEngine

To update to the latest version:

# Pull latest changes
git pull origin main

# Update Python dependencies
pip install -r requirements.txt --upgrade

# Update database schema
./scripts/migrate.sh

# Rebuild Docker images
docker-compose build --no-cache
docker-compose up -d

Uninstalling OddsEngine

To completely remove OddsEngine:

# Stop and remove Docker containers
docker-compose down -v

# Remove Docker images
docker rmi oddsengine:latest oracle-db:latest

# Deactivate and remove virtual environment
deactivate
rm -rf venv/

# Remove project directory
cd ..
rm -rf OddsEngine/

Next Steps

Quick Start Guide

Run your first probability calculation in 5 minutes

Data Integration

Set up API-Tennis integration

Architecture

Understanding OddsEngine’s system design

Contributing

Contribute to the OddsEngine project

Getting Help

If you encounter issues:

Check the GitHub Issues
Review logs in temp/application.log
Run diagnostics: python scripts/diagnose.py
Contact the development team

Academic Project: OddsEngine is developed as part of the Software Engineering Fundamentals course at Pontificia Universidad Javeriana, 2026.

Get Started

Core Concepts

User Guide

Data Integration

​Installation Guide

​System Requirements

​Hardware Requirements

​Operating System Support

Linux

macOS

Windows

​Prerequisites

​1. Docker and Docker Compose

​2. Python 3.10 or Higher

​3. Git

​Installing OddsEngine

​Running OddsEngine

​Project Structure

​Configuration Files

​config.yaml

​settings.json

​Verification Steps

​Check Docker Services

​Test Database Connection

​Test API Connection

​Run Unit Tests

​Troubleshooting

​Docker Issues

​Python Issues

​API Issues

​Permission Issues

​Updating OddsEngine

​Uninstalling OddsEngine

​Next Steps

Quick Start Guide

Data Integration

Architecture

Contributing

​Getting Help

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Hardware Requirements

Operating System Support

Prerequisites

1. Docker and Docker Compose

2. Python 3.10 or Higher

3. Git

Installing OddsEngine

Running OddsEngine

Project Structure

Configuration Files

config.yaml

settings.json

Verification Steps

Check Docker Services

Test Database Connection

Test API Connection

Run Unit Tests

Troubleshooting

Docker Issues

Python Issues

API Issues

Permission Issues

Updating OddsEngine

Uninstalling OddsEngine

Next Steps

Getting Help