Launch an Invenio instance

Prerequisites

To be able to develop and run Invenio you will need the following installed and configured on your system:

Overview

Creating your own Invenio instance requires scaffolding two code repositories using Cookiecutter:

  • one code repository for the main website.
  • one code repository for the data model.

These code repositories will be where you customize and develop the features of your instance.

Bootstrap

Before we begin, you want to make sure to have Cookiecutter installed. Invenio leverages this tool to generate the starting boilerplate for different components, so it will be useful to have in general. We recommend you install it as a user package or in the virtualenv we define below.

# Install cookiecutter if it is not already installed
$ sudo apt-get install cookiecutter
# OR, once you have created a virtualenv per the steps below, install it
(my-repository-venv)$ pip install --upgrade cookiecutter

Note

If you install Cookiecutter in the virtualenv, you will need to activate the virtualenv to be able to use cookiecutter on the command-line.

We can now begin. First, let’s create a virtualenv using virtualenvwrapper in order to sandbox our Python environment for development:

$ mkvirtualenv my-repository-venv

Now, let’s scaffold the instance using the official cookiecutter template.

(my-repository-venv)$ cookiecutter gh:inveniosoftware/cookiecutter-invenio-instance --checkout v3.0
# ...fill in the fields...

Now that we have our instance’s source code ready we can proceed with the initial setup of the services and dependencies of the project:

# Fire up the database, Elasticsearch, Redis and RabbitMQ
(my-repository-venv)$ cd my-site/
(my-repository-venv)$ docker-compose up -d
Creating network "mysite_default" with the default driver
Creating mysite_cache_1 ... done
Creating mysite_db_1    ... done
Creating mysite_es_1    ... done
Creating mysite_mq_1    ... done

If the Elasticsearch service fails to start mentioning that it requires more virtual memory, see the following fix <https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode>`_.

Customize

This instance doesn’t have a data model defined, and thus it doesn’t include any records you can search and display. To scaffold a data model for the instance we will use the official data model cookiecutter template:

(my-repository-venv)$ cd ..  # switch back to the parent directory
(my-repository-venv)$ cookiecutter gh:inveniosoftware/cookiecutter-invenio-datamodel --checkout v3.0
# ...fill in the fields...

For the purposes of this guide, our data model folder is my-datamodel.

Let’s also install the data model in our virtualenv:

(my-repository-venv)$ pip install -e .

Note

Once you publish your data model somewhere, i.e. the Python Package Index, you might want to edit your instance’s setup.py file to add it there as a dependence.

Now that we have a data model installed we can create database tables and Elasticsearch indices:

(my-repository-venv)$ cd my-site
(my-repository-venv)$ ./scripts/bootstrap
(my-repository-venv)$ ./scripts/setup

Run

You can now run the necessary processes for the instance:

(my-repository-venv)$ ./scripts/server
* Environment: development
* Debug mode: on
* Running on https://127.0.0.1:5000/ (Press CTRL+C to quit)

You can now visit https://127.0.0.1:5000/ !