Complete Setup Guide

This guide walks you through the complete setup process for FKApi, from installing dependencies to running your first API requests.

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.10 or higher
PostgreSQL 15 or higher
Git
pip and virtualenv

System Requirements

OS: Windows, Linux, or macOS
RAM: Minimum 4GB (8GB recommended)
Storage: 1GB for application and dependencies
Network: Internet connection for initial data scraping

Installation

Verification

Verify your installation by testing these endpoints:

Health Check

curl http://localhost:8000/api/health

Expected response:

{
  "status": "ok",
  "database": "connected",
  "cache": "available"
}

Test API Endpoints

# List clubs
curl http://localhost:8000/api/clubs

# Search clubs
curl http://localhost:8000/api/clubs/search?keyword=manchester

# Get seasons for a club
curl http://localhost:8000/api/seasons?club_id=1

Production Configuration

For production deployments, update your .env file:

# Security
DJANGO_SECRET_KEY=your-long-random-secret-key-here
DJANGO_DEBUG=False
DJANGO_ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

# Enable authentication
DJANGO_API_ENABLE_AUTH=True

# Use strong database credentials
POSTGRES_PASSWORD=strong-random-password

# Enable Redis and Celery for better performance
ENABLE_CELERY=True

Important Security Notes:

Never commit .env files to version control
Generate a strong DJANGO_SECRET_KEY using python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
Always set DEBUG=False in production
Use strong, unique passwords for database access
Configure HTTPS/SSL for production deployments

Running with Gunicorn (Production)

For production, use Gunicorn instead of the development server:

gunicorn --bind 0.0.0.0:8000 --workers 4 --timeout 120 fkapi.wsgi:application

Gunicorn configuration:

--workers 4: Number of worker processes (recommended: 2-4 x CPU cores)
--timeout 120: Worker timeout in seconds
--bind 0.0.0.0:8000: Bind to all interfaces on port 8000

Next Steps

Docker Deployment

Deploy FKApi using Docker and docker-compose

Celery Setup

Configure async tasks with Celery

Caching Strategy

Optimize performance with Redis caching

Monitoring

Set up Prometheus and Grafana monitoring

Troubleshooting

Database Connection Errors

If you see connection errors:

Verify PostgreSQL is running: sudo systemctl status postgresql (Linux) or pg_ctl status (Windows)
Check database credentials in .env
Ensure database exists: psql -U postgres -l
Check PostgreSQL is listening on the correct port: netstat -an | grep 5432

Module Import Errors

If you see ModuleNotFoundError:

Ensure virtual environment is activated
Reinstall requirements: pip install -r requirements.txt
Verify Python version: python --version (should be 3.10+)

Port Already in Use

If port 8000 is already in use:

Change port in .env: DJANGO_PORT=8001
Or run with custom port: python manage.py runserver 8001
Find and kill process using port: lsof -ti:8000 | xargs kill (Linux/Mac)

Permission Errors

On Linux/Mac, you may need to:

chmod +x manage.py
sudo chown -R $USER:$USER .

Environment Variables Reference

Variable	Default	Description
`DJANGO_SECRET_KEY`	(auto-generated in dev)	Secret key for Django security
`DJANGO_DEBUG`	`True`	Enable debug mode
`DJANGO_ALLOWED_HOSTS`	`localhost,127.0.0.1`	Comma-separated list of allowed hosts
`DJANGO_PORT`	`8000`	Port for development server
`DJANGO_API_ENABLE_AUTH`	`False`	Enable API authentication
`POSTGRES_DB`	`fkapi`	PostgreSQL database name
`POSTGRES_USER`	`postgres`	PostgreSQL username
`POSTGRES_PASSWORD`	`postgres`	PostgreSQL password
`POSTGRES_HOST`	`localhost`	PostgreSQL host
`POSTGRES_PORT`	`5432`	PostgreSQL port
`REDIS_URL`	`redis://localhost:6379/1`	Redis connection URL
`ENABLE_CELERY`	`False`	Enable Celery for async tasks
`CELERY_BROKER_URL`	`redis://localhost:6379/0`	Celery message broker
`CELERY_RESULT_BACKEND`	`redis://localhost:6379/0`	Celery result storage

Get Started

Core Concepts

Guides

Management Commands

Complete Setup Guide

Prerequisites

System Requirements

Installation

Verification

Health Check

Test API Endpoints

Production Configuration

Running with Gunicorn (Production)

Next Steps

Docker Deployment

Celery Setup

Caching Strategy

Monitoring

Troubleshooting

Database Connection Errors

Module Import Errors

Port Already in Use

Permission Errors

Environment Variables Reference

Additional Resources

​Prerequisites

​System Requirements

​Installation

​Verification

​Health Check

​Test API Endpoints

​Production Configuration

​Running with Gunicorn (Production)

​Next Steps

Docker Deployment

Celery Setup

Caching Strategy

Monitoring

​Troubleshooting

​Database Connection Errors

​Module Import Errors

​Port Already in Use

​Permission Errors

​Environment Variables Reference

​Additional Resources

Prerequisites

System Requirements

Installation

Verification

Health Check

Test API Endpoints

Production Configuration

Running with Gunicorn (Production)

Next Steps

Troubleshooting

Database Connection Errors

Module Import Errors

Port Already in Use

Permission Errors

Environment Variables Reference

Additional Resources