Before You Start

This guide is for experienced Django developers who wish to contribute to the development of the core FairDM framework. If you are looking for information on how to develop a FairDM-powered web application for your research community, please see the Developer Guide.

Prerequisites

Before contributing to FairDM, you should have:

Required Knowledge

• Python: Proficient in Python 3.10+ with strong understanding of object-oriented programming

• Django: Experience building Django applications; familiarity with models, views, templates, forms, and the Django ORM

• Git: Comfortable with Git workflows (branching, committing, merging, rebasing)

• Testing: Understanding of unit testing and test-driven development (pytest)

Recommended Knowledge

• Type hints: Experience with Python type annotations and mypy

• PostgreSQL: Basic understanding of relational databases

• Docker: Familiarity with containerization for development environments

• Bootstrap 5: Knowledge of Bootstrap components and grid system

• HTMX/Alpine.js: Understanding of progressive enhancement patterns (helpful but not required)

Required Tools

Before setting up the development environment, ensure you have the following installed on your system:

1. Python 3.10 or higher

   • Check version: python --version or python3 --version

   • Download from python.org

2. uv (dependency manager)

   • Install: https://docs.astral.sh/uv/getting-started/installation/

   • Check version: uv --version

3. Git

   • Check version: git --version

   • Download from git-scm.com

4. Docker

   • FairDM runs on PostgreSQL with the PostGIS extension, and docker-compose.yml starts one for you, along with Redis, the development server and a Celery worker

   • On Linux, the container runs as user id 1000. If your user has another id, add user: "<your id>:<your group id>" to the django and celeryworker services in a docker-compose.override.yml, so the container can write to your checkout

   • Download from docker.com

5. GDAL, GEOS and PROJ, only if you run Django on your own machine rather than in Docker

   • GeoDjango loads these system libraries. The development image already has them

   • Debian and Ubuntu: sudo apt install gdal-bin. macOS: brew install gdal

   • On Windows, run Django in Docker instead

   • If Django cannot find them, set GDAL_LIBRARY_PATH and GEOS_LIBRARY_PATH to the full paths of the libraries

6. A code editor

   • Recommended: Visual Studio Code with Python and Django extensions

   • Alternatives: PyCharm, Sublime Text, etc.

Tip

New to Django? If you’re not yet comfortable with Django basics, we recommend completing the official Django tutorial before contributing to FairDM.

Setting Up Your Development Environment

Tip

The quickest start is Docker. After cloning, docker compose up builds the development image and starts PostGIS, Redis, a Celery worker and the development server on http://localhost:8000, with your checkout mounted so edits reload. It needs nothing installed but Docker, on Windows the same as anywhere else. The first start installs the locked dependencies into a Docker volume, so it takes a few minutes. docker compose down --volumes removes the volume and the database, to start again from nothing. The rest of this page describes running Django on your own machine against the same databases.

Follow these steps to set up a local FairDM development environment:

1. Fork and Clone the Repository

1. Fork the repository on GitHub:

   • Navigate to FAIR-DM/fairdm

   • Click Fork in the top-right corner

2. Clone your fork to your local machine:

   git clone https://github.com/YOUR-USERNAME/fairdm.git
   cd fairdm
   

3. Add the upstream remote (to keep your fork in sync):

   git remote add upstream https://github.com/FAIR-DM/fairdm.git
   

2. Install Dependencies with uv

1. Install Python dependencies:

   uv sync
   

   This creates a virtual environment and installs all project dependencies including development tools (pytest, mypy, ruff, etc.).

2. Activate the virtual environment (optional but recommended):

   source .venv/bin/activate
   

   All subsequent commands in this guide assume you have activated the virtual environment. If you don’t activate it, prefix commands with uv run (e.g., uv run pytest).

3. Start the Database

FairDM needs PostgreSQL with the PostGIS extension, in development as in production. SQLite has no spatial support and is not an option. Start PostGIS and Redis from docker-compose.yml:

docker compose up postgres redis

stack.development.env already points a development portal at them, on localhost:5432 and localhost:6379. To use a PostGIS server of your own instead, set DATABASE_URL or the POSTGRES_* variables in your environment, which take precedence over the file.

4. Run Database Migrations

Apply all database migrations to set up the schema:

uv run python manage.py migrate

5. Create a Superuser (Optional)

To access the Django admin interface:

uv run python manage.py createsuperuser

Follow the prompts to create an admin account.

6. Run the Development Server

Start the Django development server:

uv run python manage.py runserver

Open http://localhost:8000 in your browser. You should see the FairDM homepage.

Tip

Admin interface: Access the admin at http://localhost:8000/admin using the superuser credentials you created.

7. Verify the Setup

Run the test suite to ensure everything is working:

uv run pytest

All tests should pass. If any fail, check your environment setup.

Next Steps

Now that your environment is set up, you can:

• Learn about quality gates: Understand tests, type checking, linting, and documentation builds

• Read the contribution workflow: Learn how to propose changes, create pull requests, and align with the FairDM constitution

See also

Constitution: Before making changes, read the FairDM Constitution to understand the framework’s goals and constraints.