Skip to main content
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

1
Clone the Repository
2
Clone the FKApi repository to your local machine:
3
git clone https://github.com/your-username/fkapi.git
cd fkapi
4
Create Virtual Environment
5
Create and activate a Python virtual environment:
6
# Create virtual environment
python -m venv venv

# Activate on Linux/Mac
source venv/bin/activate

# Activate on Windows
venv\Scripts\activate
7
Install Dependencies
8
Install all required Python packages:
9
pip install --upgrade pip
pip install -r requirements.txt
10
The main dependencies include:
11
  • Django 5.0.4 - Web framework
  • django-ninja 1.1.0 - 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)
  • gunicorn 21.2.0 - Production WSGI server
    • 12
    Set Up PostgreSQL
    13
    Create a PostgreSQL database for FKApi:
    14
    # Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE fkapi;

# Create user (optional)
CREATE USER fkapi_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE fkapi TO fkapi_user;

# Exit
\q
    15
    Configure Environment Variables
    16
    Copy the example environment file and customize it:
    17
    cp .env.example .env
    18
    Edit .env with your configuration:
    19
    # Django Settings
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=postgres
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

# Redis (optional)
REDIS_URL=redis://localhost:6379/1
REDIS_PORT=6379

# Celery (optional)
ENABLE_CELERY=False
CELERY_BROKER_URL=redis://localhost:6379/0
CELERY_RESULT_BACKEND=redis://localhost:6379/0
    20
    For development, you can disable Redis and Celery. FKApi will automatically fall back to local memory cache and threading.
    21
    Run Database Migrations
    22
    Apply all database migrations to set up the schema:
    23
    python manage.py migrate
    24
    This creates all necessary tables for:
    25
  • Clubs
  • Seasons
  • Kits
  • Brands
  • Competitions
  • Colors
  • User collections
    • 26
    Create Superuser
    27
    Create an admin account to access the Django admin panel:
    28
    python manage.py createsuperuser
    29
    Follow the prompts to set username, email, and password.
    30
    Load Initial Data (Optional)
    31
    If you have fixture files or want to import sample data:
    32
    python manage.py loaddata fixtures/initial_data.json
    33
    Start Development Server
    34
    Run the Django development server:
    35
    python manage.py runserver
    36
    The API will be available at:
    37
  • API endpoints: http://localhost:8000/api/
  • Admin panel: http://localhost:8000/admin/
  • Health check: http://localhost:8000/api/health

    • ​
    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:
    1. Verify PostgreSQL is running: sudo systemctl status postgresql (Linux) or pg_ctl status (Windows)
    2. Check database credentials in .env
    3. Ensure database exists: psql -U postgres -l
    4. Check PostgreSQL is listening on the correct port: netstat -an | grep 5432

    ​
    Module Import Errors

    If you see ModuleNotFoundError:
    1. Ensure virtual environment is activated
    2. Reinstall requirements: pip install -r requirements.txt
    3. Verify Python version: python --version (should be 3.10+)

    ​
    Port Already in Use

    If port 8000 is already in use:
    1. Change port in .env: DJANGO_PORT=8001
    2. Or run with custom port: python manage.py runserver 8001
    3. 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

    VariableDefaultDescription
    DJANGO_SECRET_KEY(auto-generated in dev)Secret key for Django security
    DJANGO_DEBUGTrueEnable debug mode
    DJANGO_ALLOWED_HOSTSlocalhost,127.0.0.1Comma-separated list of allowed hosts
    DJANGO_PORT8000Port for development server
    DJANGO_API_ENABLE_AUTHFalseEnable API authentication
    POSTGRES_DBfkapiPostgreSQL database name
    POSTGRES_USERpostgresPostgreSQL username
    POSTGRES_PASSWORDpostgresPostgreSQL password
    POSTGRES_HOSTlocalhostPostgreSQL host
    POSTGRES_PORT5432PostgreSQL port
    REDIS_URLredis://localhost:6379/1Redis connection URL
    ENABLE_CELERYFalseEnable Celery for async tasks
    CELERY_BROKER_URLredis://localhost:6379/0Celery message broker
    CELERY_RESULT_BACKENDredis://localhost:6379/0Celery result storage

    ​
    Additional Resources