Prerequisites
Before setting up FootyCollect locally, ensure you have the following installed:
| Requirement | Version | Notes |
|---|
| Python | 3.11+ | Required |
| PostgreSQL | 14+ | Required for database |
| Redis | 6+ | Required for caching and Celery |
| fkapi | Latest | Optional - required for Football Kit Archive integration (GitHub) |
FootyCollect integrates with the Football Kit Archive via FKAPI to search and add kits by club, season, and competition. While FKAPI is optional, it’s central to the intended workflow for discovering and cataloguing items. Installation Steps
Clone the repository
Clone the FootyCollect repository and navigate to the project directory:git clone https://github.com/sunr4y/FootyCollect.git
cd FootyCollect/footycollect
Create a virtual environment
Create and activate a Python virtual environment:python -m venv venv
source venv/bin/activate
Install dependencies
Install the required Python packages for local development:pip install -r requirements/local.txt
- Django 5.0.8 with REST Framework
- PostgreSQL adapter (psycopg)
- Redis client
- Celery for background tasks
- Development tools (pytest, mypy, ruff)
- And more (see requirements/base.txt)
Configure environment variables
Set up your environment configuration:cp deploy/env.example .env
.env and configure at minimum:
DJANGO_SECRET_KEY - Generate with Django utilitiesDATABASE_URL - Your PostgreSQL connection stringREDIS_URL - Your Redis connection string
For local development, set DJANGO_DEBUG=True. Never use this in production!
Run database migrations
Apply database migrations to set up the schema:This creates all necessary tables for:
- User management
- Collection items (jerseys, shorts, outerwear, tracksuits)
- Photos and media
- Clubs, seasons, and competitions
Create a superuser
Create an admin account to access Django admin:python manage.py createsuperuser
Collect static files
Gather static files (CSS, JavaScript, images) for serving:python manage.py collectstatic --noinput
Start the development server
Running Background Workers
FootyCollect uses Celery for background tasks like image processing and periodic cleanup.
Start Celery Worker
In a separate terminal (with your virtual environment activated):
celery -A config.celery_app worker -l info
Start Celery Beat (Scheduled Tasks)
For periodic tasks like orphaned photo cleanup:
celery -A config.celery_app beat
python manage.py setup_beat_schedule
For a complete development environment with all services (Django, PostgreSQL, Redis, Celery, Mailpit), consider using Docker Setup instead. Project Structure
Understanding the codebase organization:
footycollect/
├── config/ # Django settings and configuration
│ ├── settings/ # Environment-specific settings
│ │ ├── base.py # Base settings
│ │ ├── local.py # Local development
│ │ └── production.py # Production
│ └── checks.py # Production validation checks
├── footycollect/ # Main application code
│ ├── api/ # External API client (FKAPI)
│ ├── collection/ # Collection app (items, photos)
│ ├── core/ # Core models (clubs, seasons)
│ └── users/ # User management
├── deploy/ # Production deployment files
│ └── env.example # Environment variable template
├── requirements/ # Python dependencies
│ ├── base.txt # Base requirements
│ ├── local.txt # Development requirements
│ └── production.txt # Production requirements
└── docs/ # Architecture documentation
# Format code with Ruff
ruff format .
# Lint code
ruff check .
# Auto-fix linting issues
ruff check --fix .
Type Checking
# Run mypy for static type analysis
mypy footycollect
Running Tests
# Run all tests with coverage
pytest
# Run specific test file
pytest footycollect/collection/tests/test_models.py
# View HTML coverage report
open htmlcov/index.html # macOS
xdg-open htmlcov/index.html # Linux
Database Management
Creating Migrations
After modifying models:
python manage.py makemigrations
Applying Migrations
Resetting the Database
This will delete all data!
# Drop and recreate database (PostgreSQL)
dropdb footycollect_db
createdb footycollect_db
# Run migrations
python manage.py migrate
# Create superuser
python manage.py createsuperuser
API Documentation
When running the development server, interactive API documentation is available:
The API uses OpenAPI 3.0 specification generated by drf-spectacular.
Email Testing
For local development, Django is configured to print emails to the console by default.
For a visual email testing interface, use Docker Setup which includes Mailpit at http://localhost:8025.
Troubleshooting
Database Connection Errors
Ensure PostgreSQL is running:
# macOS (Homebrew)
brew services start postgresql@14
# Linux (systemd)
sudo systemctl start postgresql
# Check status
psql --version
Redis Connection Errors
Ensure Redis is running:
# macOS (Homebrew)
brew services start redis
# Linux (systemd)
sudo systemctl start redis
# Check status
redis-cli ping # Should return PONG
Module Import Errors
Ensure your virtual environment is activated and dependencies are installed:
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install -r requirements/local.txt
Next Steps
