Skip to main content
This guide will walk you through installing FootyCollect and creating your first item in your collection.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.11+ (required)
  • PostgreSQL 14+ (required)
  • Redis 6+ (required)
  • FKAPI (optional - required for automatic kit addition from Football Kit Archive)
FKAPI is optional but highly recommended. Without it, you can still use FootyCollect for manual entry and photo management. See FKAPI documentation for installation instructions.

​
Installation

1

Clone the repository

git clone https://github.com/sunr4y/FootyCollect.git
cd FootyCollect/footycollect
2

Create a virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
3

Install dependencies

pip install -r requirements/local.txt
This installs all required packages including:
  • Django 5.0.8 and Django REST Framework
  • PostgreSQL adapter (psycopg)
  • Redis and Celery for background tasks
  • Image processing libraries (Pillow, django-imagekit)
  • And many more dependencies listed in requirements/base.txt:1-51
4

Set up environment variables

Copy the environment template and edit it with your configuration:
# For Docker setup
cp .envs/.local/.django.example .envs/.local/.django
cp .envs/.local/.postgres.example .envs/.local/.postgres

# For non-Docker setup
cp deploy/env.example .env
Edit the file and set at minimum:
  • DJANGO_SECRET_KEY - Generate with: python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
  • DATABASE_URL - Your PostgreSQL connection string
  • REDIS_URL - Your Redis connection string (typically redis://localhost:6379/0)
5

Run database migrations

python manage.py migrate
This creates all necessary database tables including:
  • User accounts
  • Collection items (BaseItem, Jersey, Shorts, etc.)
  • Photos and media
  • Clubs, seasons, and competitions
6

Create a superuser account

python manage.py createsuperuser
Follow the prompts to create your admin account. You’ll use this to access the Django admin interface and your collection.
7

Collect static files

python manage.py collectstatic --noinput
This gathers all static files (CSS, JavaScript, images) into a single directory for serving.
8

Start the development server

python manage.py runserver
The application will be available at http://127.0.0.1:8000
For a complete development environment with all services (PostgreSQL, Redis, Celery), use Docker:
docker compose -f docker-compose.local.yml up

​
Create your first collection item

Now that FootyCollect is running, let’s add your first item to your collection.
1

Log in to your account

Navigate to http://127.0.0.1:8000 and log in with the superuser credentials you created.
2

Navigate to 'Add Item'

Click the “Add Item” button in the navigation menu or go to /collection/create/.
3

Select item type

Choose the type of item you want to add:
  • Jersey - Football shirts with specific fields for size, player name, number, etc.
  • Shorts - Match shorts
  • Outerwear - Jackets, hoodies, windbreakers
  • Tracksuit - Training tracksuits
  • Pants - Training pants
  • Other - Pins, hats, caps, socks, and other memorabilia
For this example, we’ll add a jersey.
4

Fill in item details

The form will present fields specific to jerseys:Required fields:
  • Brand - Select from existing brands or add a new one (e.g., Adidas, Nike, Puma)
  • Size - Select the jersey size (XS, S, M, L, XL, etc.)
Optional but recommended:
  • Club - The football club (e.g., Real Madrid, Barcelona)
  • Season - The season year (e.g., 2023-24)
  • Kit Type - Home, Away, Third, Goalkeeper, etc.
  • Player Name - If the jersey has a nameset
  • Number - Player number
  • Condition - From 1-10 or select detailed condition (BNWT, Excellent, etc.)
  • Main Color - Primary color of the jersey
  • Design - Plain, Stripes, Hoops, etc.
If you have FKAPI running, you can search for kits directly from the Football Kit Archive and auto-fill these fields.
Example jersey name generated automatically:
Real Madrid Home 2023-24 - L - Benzema#9 - Player Version
5

Upload photos

Add photos of your item:
  • Click “Choose Files” to select up to 10 photos
  • The first photo will be your main display image
  • Photos are automatically optimized and converted to AVIF format
  • You can reorder photos after upload
Supported formats: JPEG, PNG, WebP
6

Set privacy and tags

Configure visibility and organization:
  • Is Private - Check to keep this item visible only to you
  • Is Draft - Save as draft to continue editing later
  • Tags - Add custom tags for organization (e.g., “signed”, “match-worn”, “vintage”)
7

Save your item

Click “Save” to add the item to your collection. You’ll be redirected to the item detail page where you can:
  • View all photos in a gallery
  • See all item details
  • Edit or delete the item
  • Share with others (if public)

​
Next steps

Explore the API

Use the RESTful API to programmatically manage your collection

Set up background tasks

Configure Celery for photo processing and scheduled tasks

Deploy to production

Learn about production deployment options

Try the demo

Experiment with the live demo

Set up background tasks

Configure Celery for photo processing and scheduled tasks

Deploy to production

Deploy FootyCollect to a VPS or cloud platform

Try the demo

Explore a live demo with sample data

​
Using Docker for development

For a complete development environment with all services pre-configured: 
docker compose -f docker-compose.local.yml up
This starts:
  • Django application on port 8000
  • PostgreSQL database
  • Redis cache
  • Celery worker for background tasks
  • Celery beat for scheduled tasks
  • Mailpit for email testing (port 8025)
The first time you run Docker Compose, you’ll need to create a superuser:
docker compose -f docker-compose.local.yml run --rm django python manage.py createsuperuser

​
Common issues

​
Database connection errors

If you see database connection errors, verify:
  • PostgreSQL is running: sudo systemctl status postgresql
  • Database exists: psql -U postgres -c "\l"
  • DATABASE_URL is correct in your environment file

​
Redis connection errors

If you see Redis connection errors:
  • Check Redis is running: sudo systemctl status redis
  • Verify REDIS_URL is correct: redis://localhost:6379/0

​
Photo upload issues

If photo uploads fail:
  • Ensure the media directory is writable
  • Check Pillow is installed: pip show Pillow
  • Verify pillow-avif-plugin is installed for AVIF support

​
Migration errors

If migrations fail: 
# Reset migrations (development only - destroys data)
python manage.py migrate --fake-initial

# Or start fresh
python manage.py migrate --run-syncdb