Installation

First, create a virtualenv using virtualenvwrapper in order to sandbox our Python environment for development:

$ mkvirtualenv my-site

Start all dependent services using docker-compose (this will start PostgreSQL, Elasticsearch 6, RabbitMQ and Redis):

$ docker-compose up -d

Note

Make sure you have enough virtual memory for Elasticsearch in Docker:

# Linux
$ sysctl -w vm.max_map_count=262144

# macOS
$ screen ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/tty
<enter>
linut00001:~# sysctl -w vm.max_map_count=262144

Next, bootstrap the instance (this will install all Python dependencies and build all static assets):

$ ./scripts/bootstrap

Next, create database tables, search indexes and message queues:

$ ./scripts/setup

Running

Start the webserver:

$ ./scripts/server

Start the a background worker:

$ celery worker -A invenio_app.celery -l INFO

Start a Python shell:

$ ./scripts/console

Upgrading

In order to upgrade an existing instance simply run:

$ ./scripts/update

Testing

Run the test suite via the provided script:

$ ./run-tests.sh

By default, end-to-end tests are skipped. You can include the E2E tests like this:

$ env E2E=yes ./run-tests.sh

For more information about end-to-end testing see pytest-invenio

Documentation

You can build the documentation with:

$ python setup.py build_sphinx

UI Development

The user interface is a standalone React application created using [create-react-app](https://facebook.github.io/create-react-app/). The easiest development setup consists in starting separately Invenio, for REST APIs, and the React app using the create-react-app webserver.

First of all, you have to create your own personal access token, to be able to GET or POST data to the API:

  • start the server:

    $ ./scripts/server

  • visit https://127.0.0.1:5000/account/settings/applications/, login as admin

  • create a personal access token

  • create a file .env.development in invenio_app_ils/ui/ and add the token:

    $ echo 'REACT_APP_JWT_TOKEN=<paste token here>' > ./invenio_app_ils/ui/.env.development

  • since the React app is server under a different port (normally, :3000), you need to change extra settings on Invenio to allow requests from different domains. In config.py, change the following:

    # CORS
# ====
# change this only while developing
CORS_SEND_WILDCARD = False
CORS_SUPPORTS_CREDENTIALS = True

You won’t need these changes in production because the token is automatically retrieved by the current logged in user and the React app will be served from the same domain.

Production environment

You can use simulate a full production environment using the docker-compose.full.yml. You can start it like this:

$ docker-compose -f docker-compose.full.yml up -d

In addition to the normal docker-compose.yml, this one will start:

  • HAProxy (load balancer)
  • Nginx (web frontend)
  • UWSGI (application container)
  • Celery (background task worker)
  • Flower (Celery monitoring)