Develop¶

This documentation will guide you on how to setup your local development environment.

The installation process is composed of two parts: install and run the Invenio backend, and install and run the JavaScript frontend (Single Page Application).

Prerequisites¶

Make sure that you have installed the prerequisites below:

Python 3, at the moment we are using Python 3.9.
pipenv, e.g. via pip.
NodeJS version 14.
InvenioCLI tool (see reference)

Quick start¶

Every time you want to run InvenioILS, you will need to:

have the Docker services up and running
have the InvenioILS backend development web server and celery workers running
have the InvenioILS UI development web server running

1. Check requirements¶

To begin with, you can check if the proper requirements are installed via invenio-cli:

invenio-cli check-requirements --development

2. Scaffold project ¶

Scaffold your InvenioILS instance. Replace <version> with the version you want to install:

invenio-cli init ils
# or:
invenio-cli init ils -c v1.0.0rc1

You will be asked several questions. If in doubt, choose the default.

3. Start all dependent services using docker-compose¶

This will start PostgreSQL, Elasticsearch, RabbitMQ and Redis:

cd my-site/
docker-compose up -d

4. Build, setup and run backend part¶

# make sure that you have the right version of `setuptools`
pipenv run pip install "setuptools>=57.0.0,<58.0.0"
invenio-cli install
pipenv run invenio setup --verbose

Run the backend server:

FLASK_ENV=development pipenv run invenio run --cert docker/backend/test.crt --key docker/backend/test.key

Note The server is using a self-signed SSL certificate, which we specify in the command above. If this is not the desired behaviour, you can by-pass it by:

Changing REACT_APP_INVENIO_UI_URL and REACT_APP_INVENIO_REST_ENDPOINTS_BASE_URL variables in ui/.env file to run on http instead of https.
Running the server without specifying the certificate: FLASK_ENV=development pipenv run invenio run

Start the celery worker. In a new terminal, make sure you are in the project folder (my-site) then run:

pipenv run celery -A invenio_app.celery worker -l INFO

5. Install UI dependencies¶

Open a separate command line and install the JavaScript dependencies:

cd my-site/ui
npm install

6. Run frontend web server¶

npm start

Now visit https://127.0.0.1:3000 (accept the self-signed certificate warning if proposed). You should now see the InvenioILS website.

7. Stop it¶

When you are done, you can stop your instance and optionally destroy the containers:

To just stop the containers:

docker-compose stop