Installation Guide

Overview

This guide covers complete installation of FKApi with all features including PostgreSQL, Redis caching, and optional Celery for background tasks.

For a quick development setup, see the Quickstart Guide.

Prerequisites

Ensure you have the following installed:

Python 3.11+ (tested with 3.11)
PostgreSQL 15+ (or 12+ for development)
Redis 6+ (optional, for caching and Celery)
Git for version control
pip and virtualenv

sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip
sudo apt install postgresql postgresql-contrib
sudo apt install redis-server

brew install python@3.11
brew install postgresql@15
brew install redis

# Download Python 3.11+ from python.org
# Download PostgreSQL from postgresql.org
# Download Redis from redis.io or use Docker

Installation Steps

Clone Repository

Clone the FKApi repository:

git clone https://github.com/sunr4y/fkapi.git
cd fkapi

Create Virtual Environment

Create an isolated Python environment:

python3.11 -m venv venv
source venv/bin/activate

python -m venv venv
venv\Scripts\activate

Verify activation:

which python  # Should show path in venv folder
python --version  # Should show Python 3.11+

Install Dependencies

Install all required packages:

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

For development with testing tools:

pip install -r requirements-dev.txt

Key Dependencies Installed:

Django 5.0.4 - Web framework
django-ninja 1.1.0 - REST API framework
psycopg2-binary 2.9.9 - PostgreSQL adapter
django-redis 5.4.0 - Redis cache backend
celery 5.4.0 - Async task queue (optional)
beautifulsoup4 4.12.3 - Web scraping
cloudscraper 1.2.71 - Cloudflare bypass
django-countries 7.6.1 - Country field support

Configure Environment Variables

Copy the example environment file:

cd fkapi
cp .env.example .env

Edit .env with your configuration:

.env

# Django Settings
DJANGO_SECRET_KEY=  # Auto-generated in dev, required in production
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DJANGO_PORT=8000
DJANGO_API_ENABLE_AUTH=False

# PostgreSQL Database
POSTGRES_DB=fkapi
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Redis Cache
REDIS_URL=redis://localhost:6379/1
REDIS_PORT=6379

# Celery (Optional)
ENABLE_CELERY=True
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

# Scraper Settings
SCRAPER_USER_AGENT=FootballKitArchiveBot/1.0 (+http://yoursite.com; contact@youremail.com)

# Optional: Remote Access
# PROJECT_IP=your-server-ip

# Optional: Rate Limit Whitelist (comma-separated IPs)
# API_RATE_LIMIT_WHITELIST=127.0.0.1,192.168.1.100

Production Security:

Set DJANGO_DEBUG=False in production
Generate a strong DJANGO_SECRET_KEY
Use a secure POSTGRES_PASSWORD
Configure DJANGO_ALLOWED_HOSTS with your domain

Set Up PostgreSQL Database

Create the database:

# Create database
createdb fkapi

# Or using psql
psql -U postgres
CREATE DATABASE fkapi;
\q

docker run -d --name fkapi-postgres \
  -e POSTGRES_DB=fkapi \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: fkapi
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Verify connection:

psql -U postgres -d fkapi -c "SELECT version();"

Run Database Migrations

Apply all database migrations:

python manage.py migrate

You should see output like:

Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying core.0001_initial... OK
  ...

Create Superuser

Create an admin account:

python manage.py createsuperuser

Enter username, email, and password when prompted.

Set Up Redis (Optional but Recommended)

Start Redis server:

sudo systemctl start redis
sudo systemctl enable redis  # Auto-start on boot

brew services start redis

docker run -d --name fkapi-redis \
  -p 6379:6379 \
  redis:6-alpine

Test Redis connection:

redis-cli ping
# Should return: PONG

Verify Installation

Start the development server:

python manage.py runserver

Test the API:

# In another terminal
curl http://localhost:8000/api/health

Expected response:

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

Optional: Celery Setup

Celery enables background task processing for scraping operations.

Celery is optional. The system automatically falls back to threading if Celery is not available.

Install Celery

Celery is included in requirements.txt, but verify:

pip list | grep celery
# celery 5.4.0
# django-celery-beat 2.6.0

Configure Celery

Ensure these settings in .env:

ENABLE_CELERY=True
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0

Start Celery Worker

# Start worker
celery -A fkapi worker -l info

# Or use the provided script
chmod +x start_celery_worker.sh
./start_celery_worker.sh

# Use the batch script
start_celery_worker.bat

Start Celery Beat (Scheduled Tasks)

# Start beat scheduler
celery -A fkapi beat -l info

# Or use the provided script
chmod +x start_celery_beat.sh
./start_celery_beat.sh

start_celery_beat.bat

Monitor with Flower

Flower provides a web UI for monitoring Celery:

celery -A fkapi flower --port=5555

Access at: http://localhost:5555

Production Deployment

Security Settings

For production, update .env:

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

# HTTPS Settings
SECURE_SSL_REDIRECT=True
SECURE_HSTS_SECONDS=31536000  # 1 year

# Database with connection pooling
POSTGRES_PASSWORD=strong-random-password

Use Gunicorn

Gunicorn is included in requirements.txt:

# Start with 4 workers
gunicorn fkapi.wsgi:application --bind 0.0.0.0:8000 --workers 4

Nginx Configuration Example

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /path/to/fkapi/static/;
    }
}

Systemd Service Example

Create /etc/systemd/system/fkapi.service:

[Unit]
Description=FKApi Django Application
After=network.target postgresql.service redis.service

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/fkapi/fkapi
Environment="PATH=/path/to/fkapi/venv/bin"
ExecStart=/path/to/fkapi/venv/bin/gunicorn \
    --workers 4 \
    --bind 0.0.0.0:8000 \
    fkapi.wsgi:application

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable fkapi
sudo systemctl start fkapi
sudo systemctl status fkapi

Environment Variables Reference

Django Settings

Variable	Default	Description
`DJANGO_SECRET_KEY`	Auto-generated in dev	Secret key for cryptographic signing (required in production)
`DJANGO_DEBUG`	`True`	Debug mode (set to `False` in production)
`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 key authentication

Database Settings

Variable	Default	Description
`POSTGRES_DB`	`fkapi`	Database name
`POSTGRES_USER`	`postgres`	Database user
`POSTGRES_PASSWORD`	`postgres`	Database password
`POSTGRES_HOST`	`localhost`	Database host
`POSTGRES_PORT`	`5432`	Database port

Cache Settings

Variable	Default	Description
`REDIS_URL`	`redis://localhost:6379/1`	Redis connection URL for cache
`REDIS_PORT`	`6379`	Redis port

Celery Settings

Variable	Default	Description
`ENABLE_CELERY`	`True` (if available)	Enable Celery background tasks
`CELERY_BROKER_URL`	`redis://localhost:6379/0`	Celery message broker URL
`CELERY_RESULT_BACKEND`	`redis://localhost:6379/0`	Celery result backend URL
`FLOWER_PORT`	`5555`	Port for Flower monitoring interface

Scraper Settings

Variable	Required	Description
`SCRAPER_USER_AGENT`	Yes	User agent string for web scraping (must include contact info)
`HTTP_TIMEOUT`	`15`	HTTP request timeout in seconds
`HTTP_MAX_RETRIES`	`3`	Maximum number of retry attempts
`HTTP_BACKOFF_FACTOR`	`0.5`	Exponential backoff factor for retries
`DELAY_MIN`	`2`	Minimum delay between requests (seconds)
`DELAY_MAX`	`5`	Maximum delay between requests (seconds)

Rate Limiting

Variable	Default	Description
`API_RATE_LIMIT_WHITELIST`	Empty	Comma-separated list of whitelisted IP addresses

Troubleshooting

PostgreSQL Connection Issues

# Check PostgreSQL is running
sudo systemctl status postgresql
pg_isready

# Verify database exists
psql -U postgres -l | grep fkapi

# Test connection with credentials from .env
psql -U postgres -d fkapi

Redis Connection Issues

# Check Redis is running
redis-cli ping

# View Redis info
redis-cli info

# Monitor Redis commands
redis-cli monitor

Migration Errors

# Show migration status
python manage.py showmigrations

# Fake migrations if needed (careful!)
python manage.py migrate --fake

# Reset database (development only)
python manage.py flush
python manage.py migrate

Celery Not Starting

# Check Redis connection
redis-cli ping

# Verify Celery config
python manage.py shell
>>> from django.conf import settings
>>> print(settings.CELERY_BROKER_URL)

# Check worker logs
celery -A fkapi worker -l debug

Next Steps

Quickstart Guide

Make your first API call

API Reference

Explore all endpoints

Scraping Guide

Learn ethical data collection

Admin Interface

Manage data via Django admin

Get Started

Core Concepts

Guides

Management Commands

Installation Guide

Overview

Prerequisites

Installation Steps

Optional: Celery Setup

Install Celery

Configure Celery

Start Celery Worker

Start Celery Beat (Scheduled Tasks)

Monitor with Flower

Production Deployment

Security Settings

Use Gunicorn

Nginx Configuration Example

Systemd Service Example

Environment Variables Reference

Django Settings

Database Settings

Cache Settings

Celery Settings

Scraper Settings

Rate Limiting

Troubleshooting

PostgreSQL Connection Issues

Redis Connection Issues

Migration Errors

Celery Not Starting

Next Steps

Quickstart Guide

API Reference

Scraping Guide

Admin Interface

​Overview

​Prerequisites

​Installation Steps

​Optional: Celery Setup

​Install Celery

​Configure Celery

​Start Celery Worker

​Start Celery Beat (Scheduled Tasks)

​Monitor with Flower

​Production Deployment

​Security Settings

​Use Gunicorn

​Nginx Configuration Example

​Systemd Service Example

​Environment Variables Reference

​Django Settings

​Database Settings

​Cache Settings

​Celery Settings

​Scraper Settings

​Rate Limiting

​Troubleshooting

​PostgreSQL Connection Issues

​Redis Connection Issues

​Migration Errors

​Celery Not Starting

​Next Steps

Quickstart Guide

API Reference

Scraping Guide

Admin Interface

Overview

Prerequisites

Installation Steps

Optional: Celery Setup

Install Celery

Configure Celery

Start Celery Worker

Start Celery Beat (Scheduled Tasks)

Monitor with Flower

Production Deployment

Security Settings

Use Gunicorn

Nginx Configuration Example

Systemd Service Example

Environment Variables Reference

Django Settings

Database Settings

Cache Settings

Celery Settings

Scraper Settings

Rate Limiting

Troubleshooting

PostgreSQL Connection Issues

Redis Connection Issues

Migration Errors

Celery Not Starting

Next Steps