Getting Started

This is a guide that will get you started with Froide. If you plan to setup a site based on Froide, you should not run Froide directly, but instead use Froide as a dependency in your own project.

Set up the development environment

Froide requires Python 3.5+. You should be using a Python 3 virtual environment or similar setup. Setup a virtual environment for development with `venv`like so:

# Create virtualenv
python -m venv venv
# Activate it
source venv/bin/activate

Get the source code with Git from the GitHub repository:

git clone git://
cd froide

Install the libmagic library, which is a system requirement. See for details.

Install the requirements inside the virtual env with pip:

pip install -r requirements.txt

This installs the Python dependencies into the virtual environment.

Froide requires one of Django’s geospatial database backends.

Froide is designed to run with the PostgreSQL database with PostGIS extension. You may be able to use a different Django-supported geospatial database, but it is not recommended. Elasticsearch is used as a search engine.

You can install these services as you wish. There is a docker-compose.yml that provides a set of these services for use with Docker.

You need to configure these services in your Django settings or via environment variables. There’s a that can be used to locally override settings.

After configuring database and search engine, run database migrations:

python migrate

Now you can already start the web server:

python runserver

Visit http://localhost:8000 and there is your running Froide instance!

You can quit the server (Ctrl+C) and create a superuser account:

python createsuperuser

Add basic database objects

The following guide creates some database objects that are needed for running a Froide instance. You can also take shortcut and load example objects:

python loaddata publicbody.json

However, if you want to set stuff up properly, continue reading.

Run the web server again and login to the admin interface at http://localhost:8000/admin/ with the credentials of your superuser.

The first thing you should do is create a jurisdiction. Click on “Jurisdiction” in the “Publicbody” section and then on “Add Jurisdiction”. Name your jurisdiction however you want (e.g. Federal). If you only ever intend to have one, the name will not even show up. Click “Save” to continue.

Go back into the public body section and add an FOI law. Give it a name (e.g. Freedom of Information Act) and choose a jurisdiction. There are many more things that can be configured, but you can leave them for now.

Now you can add your first public body by going back to the public body section and clicking on “Add” next to “Public Bodies”. Give it a name (e.g. Ministry of the Interior). Click on the little plus-sign next to “classification” to add a topic for this public body. The classification is to distinguish different areas of government (e.g. “Ministry”, “Council”). If you want to make a request to this public body, it needs to have an email address. Select your previously created jurisdiction and FOI law and save.

You should also fill out your user details like your name in the user section of the admin.

Now you are ready to make your first request. Go back to the front page and give it a go. You can also find out more about the Froide Admin.

Custom settings

By default the Django Web server uses the file in the froide directory (the froide.settings Python module). This will be fine for your first experiments but if you want to customize your froide instance you will want your own settings file.

Go into the froide directory and copy the to

cd froide

Now you can customize that settings file to your liking.

Search with Elasticsearch

An example configuration for Elasticsearch would look like this:

    'default': {
        'hosts': 'localhost:9200'

Background Tasks with Celery

From the standard settings file everything is already setup for background tasks except that they are not running in the background.

You need to change the CELERY_ALWAYS_EAGER setting to False in your custom settings:


You need a broker for Celery. Find out more at the Celery Docs.

We recommend RabbitMQ as broker. Install it and then start it in a different terminal like this:


After you started the broker open yet another terminal, activate your virtual environment and run the celery worker like this:

python celeryd -l INFO -B

Now your server will send background tasks to Celery. Lots of common tasks are designed as background tasks so that an ongoing HTTP request can send a response more quickly. The following things are designed as background tasks:

  • Search Indexing: Updates to database objects are indexed in the background
  • Email Sending: When an action triggers an email, it’s sent in the background
  • Denormalized counts on database objects

Celery also takes the role of cron and handles periodic tasks. These are setup in the CELERYBEAT_SCHEDULE setting.