Development Environment

Getting the source

To get started, clone the repository:

$ git clone https://github.com/ESSolutions/ESSArch

Setting up virtual Python environments

You will need Python 3.12 along with pip, which is what the backend of ESSArch is built on. It is recommended to have ESSArch in its own virtual python environment.

Creating and managing virtual environments can be done with the virtualenv Python package or using more advanced tools such as pyenv or pipenv.

Installing Python dependencies

Run the following to install ESSArch and its Python dependencies:

$ cd ESSArch_Core
$ pip install -e .

ESSArch Core also contains a number of extra dependencies depending on the needs of the target environment. These are listed in the extras_require section of the setup.py file at the root of the directory and are installed by appending a list of extras to the command above.

For example, to install the requirements for building the docs and running the tests:

$ cd ESSArch_Core
$ pip install -e .[docs,tests]

Setting environment variables

If you have a config and/or plugin directory, these will also have to be added to the PYTHONPATH variable.

export PYTHONPATH=$PYTHONPATH:/ESSArch/config/:/ESSArch/plugins

Configuring services

ESSArch requires a relational database, RabbitMQ, Redis and Elasticsearch. Each service can be configured in the configuration file.

Running migrations

All changes to the database are applied using the migrate command:

$ python manage.py migrate

Installing initial data

Use the installation script in ESSArch Core to setup the default configuration

$ python ESSArch_Core/install/install_default_config.py

Important

The paths created has to exist in the filesystem before being used. See Directory Structure for the default structure

Building the frontend

To build the frontend you need Node.js LTS with yarn installed, Then to build:

$ cd frontend/static/frontend
$ yarn
$ yarn build:dev

Starting the development web server

To start the development web server provided by Django, run the following in the project root directory:

$ python manage.py runserver

You can now access ESSArch from your web browser by visiting http://localhost:8000/

Starting background workers

Much of the work in ESSArch is done using background workers. These needs to run in addition to the web server. Run the following in the project root directory:

$ essarch worker

Starting background beat processes

Background beat processes are also needed to run some operations continuously. Run the following in the project root directory:

$ essarch beat