ORCID Hub Installation

NB the Hub is intended to be, and the core code is, cross-platform; however it’s much simpler to get a fully functioning instance with *nix. Install instructions for an evaluation Hub instance on Windows will follow as the kinks are worked out.

There are three different routes to getting an ORCID Hub instance up and running:

  • managing the dependencies yourself

    • via the ORCID-Hub PyPI Python package

    • setting up from the GitHub source

  • via the orcidhub Docker Image

Reasons to choose between the route:

The Docker image, and to a lesser extent the PyPI package, gives a very quick to launch an instance of the Hub for evaluation. With the PyPI package you need to add sendmail and redis for typical functions; while running from source will also be prompted to set up the backend database. Running from the GitHub source will be a little slower to get going and involves more moving parts but provides the easiest way to allow you to customise the look and feel to suit your Consortium. NB all routes out of the box will launch an unmodified version of the NZ ORCID Hub including local references to New Zealand and the Royal Society Te Apārangi.

Managing the dependencies yourself

The Hub requires Python 3.x. We recommend both Python3.6, and running the Hub with a virtual environment, e.g. in your working directory:

virtualenv -p python3.6 venv
. ./venv/bin/activate

The Hub uses a database backend, with either SQLite or PostgreSQL supported. We currently recommend PostgreSQL 11. NB if no database url is given the Hub defaults to an embedded SQLite store.

Before you start you need to establish a means of authenticating the user

In order to enable login via ORCID you’ll need to acquire ORCID API credentials for your Hub. As this is only an ‘authenticate’ call, the public API is fine. If you’re new to the ORCID API, public API credentials for the ORCID sandbox can be obtained like so:

To enable Identity Federation SSO, you’ll either need to configure your Hub instance as a Shibboleth Service Provider. As well as registering your instance SP, running Shibboleth also comes with its own dependency of Apache. See: Shibboleth installation and SP Creation.

As an alternative to setting up the instance as a SP, it is possible to run the application as a stand-alone Python Flask application and use another remote application for user authentication. For example, if the remote SP is being provided by https://dev.orcidhub.org.nz, all you need is to set up the EXTERNAL_SP environment variable, e.g.,

export EXTERNAL_SP=https://dev.orcidhub.org.nz/Tuakiri/SP

Optional dependencies

To enable the Hub to send email and act on task queues, you’ll need to install redis for your environment as well as configuring your environment’s sendmail service. More information on setting up sendmail can be found here: Sendmail Configuration.

The NZ ORCID Hub uses Sentry for error tracking and user feedback. We’ve found it a great service, but this is optional and likely unnecessary for any evaluation.

Setting environment variables

A Hub instance needs a range of environment variable to be set in order to function. These can be set manually or by script at each runtime or, for ease, managed via a settings.cfg file. The variables that must be set in your environment are: FLASK_APP, PYTHONPATH, and if you’re using them DATABASE_URL and EXTERNAL_SP, e.g.:

export FLASK_APP=orcid_hub
export FLASK_ENV=development
DIR='$( cd '$( dirname '${BASH_SOURCE[0]}' )' && pwd )'
export PYTHONPATH=$DIR
export LANG=en_US.UTF-8
export DATABASE_URL='postgresql://orcidhub:****@localhost:5432/orcidhub'
export EXTERNAL_SP='https://dev.orcidhub.org.nz/Tuakiri/SP'

For convenience you might want to script this initial setup.

The following variables can be provided by either settings.cfg placed in the /instance folder OR by directly exporting to the environment:

Variable

Description

ENV

The runtime environment name (default: dev)

DEFAULT_COUNTRY

The Country default for any ORCID writes (default: NZ)

NOTE_ORCID

Default note text for ORCID API requests (default: An NZ ORCID Hub integration for)

CRED_TYPE_PREMIUM

The default type of credentials requested (default: 2, i.e,. “Premium Member”)

APP_NAME

Default App name prefix for ORCID API requests (default: NZ ORCID HUB for)

APP_DESCRIPTION

Default App description prefix for ORCID API requests (default: This is an ORCID integration through the NZ ORCID HUB connecting)

Configuring authentication services, i.e., in the absence of EXTERNAL_SP, or if using ORCID only

Variable

Description

SHIB_IDP_DOMAINNAME

Your Identity Providers domain name (default: http://directory.tuakiri.ac.nz)

SHIB_METADATA_CERT_FILE

Meta data signing certificate location (default: conf/tuakiri-test-metadata-cert.pem)

SHIB_METADATA_PROVIDER_URI

Shibboleth SAML 2.0 meta data provider URI [NativeSPMetadataProvider](https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPMetadataProvider) (default: https://engine.surfconext.nl/authentication/idp/metadata)

SHIB_SP_DOMAINNAME

Your Service Providers domain name (default: ${ENV}.<container domainname>)

SHIB_SSO_DS_URL

SSO discovery service URL (default: https://${SHIB_IDP_DOMAINNAME}/ds/DS)

ORCID_CLIENT_ID

Orcid API client ID and secret, e.g., 0000-1234-2922-7589

ORCID_CLIENT_SECRET

Orcid API client ID and secret, e.g., b25ab710-89b1-49e8-65f4-8df4f038dce9

Configuring the attribute mapping for your SP. These should match the attributes exposed by your service provider (e.g. Shibboleth):

Variable Description ========================== ================== MAIL_SERVER Mail server’s name or IP (default: dev.orcidhub.org.nz) MAIL_PORT Port for sending mail (default: 25) MAIL_DEFAULT_SENDER Mail from Hub to be sent as (default no-reply@orcidhub.org.nz) MAIL_DKIM_DOMAIN Domain name to use for DKIM signed mail (default orcidhub.org.nz) MAIL_DKIM_SELECTOR Selector for DKIM signed mail (default default) MAIL_SUPPORT_ADDRESS Helpdesk email address, used in errors and as default Reply-To (default orcid@royalsociety.org.nz) RQ_REDIS_URL Redis server for rq (default redis://localhost:6379/0) ========================== ==================

Optional variables

Variable

Description

SECRET_KEY

To specify the Hub secret key for data encryption (optional)

SENTRY_DSN

Sentry project DSN (optional)

GA_TRACKING_ID

Google Analytics Tracking ID (optional)

CSRF_DOMAINS

Semicolon delimited whitelist of FQDNs, used to check Referer headers (default localhost;c9users.io)

Minimal deployment via PyPI

Assuming you have created and activated your Python 3.6 virtual environment and are in your working directory, a minimal ORCID Hub instance can be quickly set up with PyPI package and the following steps:

pip install -U 'orcid-hub'

By default the PyPI application creates an embedded Sqlite3 database. To use another backend, specify the engine and location via the DATABASE_URL environment variable from its default (sqlite:///data.db). Ensure the environment variables are set, settings.cfg is configured, and then create the first user as a Hub Administrator

orcidhub cradmin myadmin@mydomain.net --orcid YOUR-ORCID-ID -O YOUR-ORGANISATION-NAME

This command will create a Hub Admin user with email myadmin@mydomain.net, and if using ORCID authentication, i.e., you’ve set ORCID API credentials, YOUR-ORCID-ID, and at the same time registering the first organisation with YOUR-ORGANISATION-NAME.

Launch the Hub with:

orcidhub run

The result you can expect is for the terminal to start logging HTTP requests to the new development Hub instance that you are serving from your localhost. Navigate to this instance in any modern browser and you should be able to sign in with your chosen service.

NB: However until the rq worker and scheduler are running this instance will not be able to action batch tasks and so won’t send mail.

Minimal deployment via GitHub source

Running the Hub from source is very similar to setting up from the PyPI orcid-hub package. Ensure that git is installed and then from a terminal, clone the Hub source into a suitable location and if desired switch to the branch. NB: default master is Hub’s core development branch, origin/prod is the most current stable production release. The folder NZ-ORCID-Hub now becomes your working directory:

git clone https://github.com/Royal-Society-of-New-Zealand/NZ-ORCID-Hub.git
cd NZ-ORCID-Hub
git checkout origin/prod

Create the additional directories that a running Hub will require, enable the recommended python virtual environment, and install the Hub’s requirements:

mkdir -p data/redis pgdata
virtualenv -p python3.6 venv
. ./venv/bin/activate
sudo apt install python3.6-dev
pip install -U pip
pip install -U -r dev_requirements.txt

Set environment variables, and (optionally) create and configure instance/settings.cfg. NB by pulling source code the instance folder will have been created with a settings.sample.cfg that can be used as a guide.

Once the environment has been set up you create the Hub superuser and launch for the first time:

export FLASK_ENV=development
export FLASK_APP=orcid_hub
flask cradmin myadmin@mydomain.net --orcid YOUR-ORCID-ID -O YOUR-ORGANISATION-NAME
flask run

The terminal should show the Hub logging, and served from localhost. As with PyPI, additional processes are needed for this instance to start responding to tasks.

Launch queue worker and a scheduler

To enable the Hub to action tasks, redis must be installed and running, and two additional processes need to be active. The easiest way to launch these is opening another terminal, navigate to the project directory and enable your virtual python environment. Set up at least the PYTHONPATH, FLASK_APP and FLASK_ENV environment variables (and if non-default RQ_REDIS_URL). Once the environment established, launch these processes with either:

For a PyPI-based instance or

orcidhub rq scheduler & orcidhub rq worker --logging_level info

For a source-based instance.

./flask.sh rq scheduler & ./flask.sh rq worker --logging_level info

In either case this terminal should now report the birth of the worker process, and a fully functioning test Hub should now be being served.