[[TOC]]

Pushing Together is an open-source web platform to manage participative opinion research, with a built-in machine learning algorithm to generate opinion groups from participation data. You can visit EJ at https://www.ejplatform.org. For detailed information on developing and using our system, please refer to the documentation. For contributions, issues or feature requests join us on https://github.com/cidadedemocratica/ej-application.

Getting started with Docker

1. Clone the repository

     git clone https://gitlab.com/pencillabs/ej/ej-application
     cd ej-application

2. Install docker compose plugin

3. Check your Python version

python -V

If your Python version is higher than 3.12, you will need to install version 3.12. We recommend the pyenv tool to install the 3.12 version without breaking the rest of your local environment. You can use the pyenv local 3.12 command to set the Python version only for the EJ repository.

4. Install the application

pip install poetry
eval $(poetry env activate)
poetry install
cp .env.sample .env
inv build
inv up

This will deploy EJ using the docker/docker-compose.yml file. Every code change will be synchronized with the server service. After inv up, you can access EJ at http://localhost:8000.

From here, you can check our guides to explore EJ participative features and more advanced development documentation.

If you are creating a clean instance, you can populate the database with some fake data using the command inv exec "inv db-fake".

Alternatively, if you wish to clean your database and repopulate it using the script, you'll need to remove the docker_backups volume. After that, run inv up command and then inv exec "inv db-fake", as mentioned previously. To rebuild the server image, you can run inv build --no-cache.

macOS

If you are using a Mac with an Intel chip, the above process may work for you. If not, you can follow the steps below.

You will have to set up a virtual machine (Linux), preferably UTM for Apple silicon as VirtualBox for Apple silicon is still unstable and crashes every 15 min as of May 2024. If you want to set up a virtual machine on an Intel-based Mac, even VirtualBox is a good choice. Follow https://dev.to/ruanbekker/how-to-run-a-amd64-bit-linux-vm-on-a-mac-m1-51cp, for VM setup. Then normally download all dependencies (git, python, pip, docker, code-editor) on the virtual device.

1. Set up the Docker Compose plugin
2. Install invoke and the Django environment

python -m venv ../virtualenvs/ej/
source ../virtualenvs/ej/bin/activate
poetry install
cp .env.sample .env
inv up

3. Build the server Docker image

inv build --no-cache

4. Create the containers

inv up

Celery and RabbitMQ

EJ uses Celery for asynchronous task processing, with RabbitMQ as the message broker.

Clustering

The main use of Celery in EJ is for opinion clustering processing. When a conversation needs to update its opinion groups (clusters), this task is executed asynchronously to avoid blocking the application. The Docker celery service is responsible for running the Celery worker.

Task Logs

To monitor Celery task logs:

inv celery-logs

Available Tasks

Task	Description
update_clusterization	Updates clusters for a conversation

Available commands

Some useful commands to manage the Docker environment:

Command	Description
inv up	Creates EJ containers and runs the application
inv build	Builds EJ server Docker image
inv logs	Shows Django logs
inv celery	Runs Celery worker
inv celery-logs	Shows Celery logs
inv stop	Stops EJ containers
inv rm	Removes EJ containers
inv attach	Connects to Django container
inv exec	Executes a shell command inside Django container

Some useful commands to manage the application (run this inside the Django container):

Command	Description
inv i18n	Extracts messages from Jinja templates for translation
inv i18n -c	Compile .po files
inv sass	Compile .sass files for all EJ apps
inv sass --watch	Watch changes on code, and compile .sass files for all EJ apps
inv collect	Moves compiled files (css, js) to Django static folder
inv db	Prepare database and run migrations
inv shell	Executes Django shell with IPython
inv docs	Compile .rst documentation to generate .html files
inv celery	Runs Celery worker

Tests

If you are making changes to EJ codebase, do not forget to run tests frequently. EJ uses Pytest:

inv test

Beyond unit and integration tests, EJ also has e2e tests implemented with Cypress. Check src/ej/tests/e2e/README.md for more information.

API

EJ API's auto-generated documentation and endpoints will be available at http://localhost:8000/api/v1/swagger/.

Guides

After configuring the local environment, the next step is reading our documentation. It can be generated with:

inv exec "inv docs"

and will be available at http://localhost:8000/docs.