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.

See also

Configuration

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