To report a bug, please open an issue on our Github. To maximize the chance of getting help from our team and our community, we advise you to be as precise as possible, while detailing:

• your Operating System (Mac, Windows or Linux)

• the version of your Operating System

• the version of Prophecies

• screenshots of your issue

If for confidentiality reasons you don't want to open an issue on Github, please write to .

Why did we create Prophecies?

ICIJ is a non-profit leading outstanding investigations involving hundreds of reporters around the world. Each of our project leverage the power of data and technology to investigate issues of global importance. To be able to simultaneously publish a story in so many media, every single line of data we use must be fact checked. This is, as we say internally, "our secret sauce". Some of the datasets we produce rely on a very heavy effort to be verified, sometimes with up to 4 different rounds of verification.

In order to make sure this workflow is well organized and efficient, we created Prophecies.

How can I use Prophecies?

Prophecies is a collaborative tool that must be available online to its users. Therefore, to use Prophecies you must install it on your server, as web application.

What skills are needed to install Prophecies?

Prophecies is a Python application built at the top of the Django framework. To ease installation, we publish a Docker image of the application . The image is built both for ARM64 and AMD64 which ensure a wider level of compatibility.

To install Prophecies, you will need to have a good understanding of how Docker and Docker Compose work and how they can be used. You will also need to have basic knowledge of how to setup a PostgreSQL database. In this guide, we will use a database directly installed in a Docker.

This page introduce the key concepts used by Prophecies.

The application can be configured using the following environment variables:

Prerequisites

Before installing Prophecies, ensure you have the following tools installed:

• Docker: A platform for developing, shipping, and running applications inside isolated environments known as containers. Learn more about Docker.

• Docker Compose: A tool for defining and running multi-container Docker applications. It uses a YAML file to configure your application's services, making it easier to manage complex setups. .

These tools are essential for running Prophecies efficiently and are widely used in the development and deployment of modern applications.

Setup steps

1. Prepare the Working Directory

Place this docker-compose.yml file in your chosen directory. This will be the working directory for your Docker Compose setup:

2. Configure NGINX

You need to create an NGINX configuration file as referenced in your Docker Compose file (./nginx.conf). Ensure this file is correctly configured to serve your Prophecies. It should be set up to listen on port 9999 and serve static files from the /static/ directory:

3. Starting Services

In your working directory, run the following command:

This command will download the necessary images (if not already downloaded), create the defined volumes, and start the services as background processes.

3. Database Migrations and Static Files

The docker-compose.yml file specifies services for running database migrations (migration) and collecting static files so they can be served by NGINX (collectstatic). These services should automatically perform these tasks when you start Docker Compose.

4. Create Admin User

The database is currently empty, without user. To provision your first admin user, you must use the command line:

5. Accessing the Application

Once all services are up and running, the application should be accessible via :

6. Monitoring and Logs

To monitor the status of your Docker containers and check for any issues, you can use the Docker Compose logs command:

The -f flag will follow the log output, allowing you to see real-time logs as they are generated.

7. Stopping and Removing Services

To stop the services without removing them, you can run:

If you need to stop and remove all the containers, networks, and volumes associated with your Docker Compose setup, use the down command:

Additional Notes

• This configuration doesn't include SSL setup for NGINX, which is recommended for production.

• Regularly check for updates to the icij/prophecies image to keep your application up to date.

• To use custom domain, don't forget to update the ALLOWED_HOSTS

Once you setup Prophecies from the sources, simply launch Pytest with this shortcut:

make test-back

This command triggers the testing process, where make is a build automation tool used to manage tasks like compiling the code or running tests, and test-back is a target defined within the Makefile.

Upon execution, Pytest will begin to run all the specified tests in your test suite. You can monitor the output in your terminal to check the progress of the tests. If all goes well and your code passes all the tests, you should see a success message indicating that everything is working as intended. Any failed tests will be reported accordingly, allowing you to make the necessary adjustments.

API

The API is built with Django Rest Framework and implements the key concepts of Prophecies.

Stack

Prophecies is based on the following open source tools:

• Python 3.9, 3.10

• Node 16, 18

• Django 4.2

Interaction workflow

This sequence diagram illustrates the communication flow within the Prophecies platform infrastructure, focusing on how a request travels from the user interface to the database and back.

Database schema

Here is a simplified version of the Database schema.

Docker image tag

The Docker image is tagged with the version extracted from the git tag (e.g., icij/prophecies:1.0.0). Additionally, the image is tagged as latest.

• Image Repository:

• Platform: linux/arm64, linux/amd64

This documentation provides a comprehensive guide on how to release a new Docker image, build, and test the application locally using the provided Makefile commands.

Releasing a new Docker Image

1. Update Version

The version can be updated as major, minor, or patch using the Makefile. To do this, run one of the following commands depending on the type of version bump you need:

These commands automatically update the version in pyproject.toml for the Python backend and package.json in the frontend directory, then commit these changes and tag the version in Git.

2. Push the Changes and Tag to Git

After updating the version and creating a git tag, push the changes and the tag to your git repository:

Pushing the tag is crucial because the GitHub Actions workflow for Docker image publishing is triggered by a push to tags that follow the semantic versioning format, prefixed with v (e.g., v1.0.0).

Build and test locally

A convenience docker-compose.yml file is located as the root of the repository. To build and test Prophecies locally with Docker, you can run from the app's root directory:

Prerequisites

• Python 3.9

• Node 16.x

• Poetry >= 1.2

Setup steps

Checkout the repository with git:

After entering the directory, setup a virtualenv with poetry and to install required packages:

To setup the database (using SQLite3 by default):

To create a superuser:

For more customization, this app utilizes inspired environment variables to configure your Django application. You can create .env file using the custom settings variables:

The application can be configured with .

Once you setup Prophecies from the sources, simply launch Jest with this shortcut:

make test-front

This command triggers the testing process, where make is a build automation tool used to manage tasks like compiling the code or running tests, and test-front is a target defined within the Makefile.

Upon execution, Jest will begin to run all the specified tests in your test suite. You can monitor the output in your terminal to check the progress of the tests. If all goes well and your code passes all the tests, you should see a success message indicating that everything is working as intended. Any failed tests will be reported accordingly, allowing you to make the necessary adjustments.

Mock Service Worker

This application utilizes (MSW) to mock API results from the backend. All server request are defined within handers that you can find :

Prophecies' GitHub Actions workflow is designed to automate the process of linting, testing, and publishing Docker images. This workflow triggers on every push to the repository and is structured into several jobs to ensure code quality and reliability before a new Docker image is published.

Jobs Overview

The workflow consists of six main jobs.

lint-backend

• Purpose: Lints the backend code to ensure it adheres to Python coding standards.

• Python Version: Runs with Python 3.9.

• Command: Uses pylint to lint the prophecies directory.

test-backend

• Purpose: Executes backend tests to verify the functionality.

• Python Version: Tests are run on both Python 3.9 and 3.10.

• Command: Runs backend tests using the make test-back command.

test-frontend

• Purpose: Conducts frontend tests to ensure UI/UX integrity.

• Node Version: Tests are conducted on Node.js versions 16.x and 18.x.

• Command: Frontend tests are executed using the make test-front command.

build

• Purpose: Build artifacts to be publish with the next release.

• Conditions: This job runs only if the push event is a tag push starting with 'v', and it depends on the successful completion of the lint-backend, test-backend, and test-frontend jobs.

package-publish

• Purpose: Restore artifacts from the build job to publish them as Github Release.

• Conditions: This job runs only if the push event is a tag push starting with 'v', and it depends on the successful completion of the build job.

docker-publish

• Conditions: This job runs only if the push event is a tag push starting with 'v', and it depends on the successful completion of the build job.

• Step: This job includes checking out the code, setting up QEMU and Docker Buildx, logging into Docker Hub, preparing the tag name based on the git tag, and finally building and pushing the Docker image.

Secrets

To be able to push on the Docker Hub, this workflow must use the following secrets:

• DOCKERHUB_USERNAME: The username for Docker Hub authentication.

• DOCKERHUB_PASSWORD: The password or access token for Docker Hub authentication.