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://github.com/okfde/froide.git
cd froide

Install the libmagic library, which is a system requirement. See https://github.com/ahupp/python-magic#dependencies 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. https://docs.djangoproject.com/en/1.11/ref/contrib/gis/install/#spatial-database.

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 local_settings.py.example that can be used to locally override settings.

After configuring database and search engine, run database migrations:

python manage.py migrate

Now you can already start the web server:

python manage.py 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 manage.py 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 manage.py 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 settings.py 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 local_settings.py.example to local_settings.py:

cd froide
cp local_settings.py.example local_settings.py

Now you can customize that settings file to your liking.

Search with Elasticsearch

An example configuration for Elasticsearch would look like this:

ELASTICSEARCH_INDEX_PREFIX = 'froide'
ELASTICSEARCH_DSL = {
    '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:

CELERY_ALWAYS_EAGER = False

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:

rabbitmq-server

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

python manage.py 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.