Application Docker Image

Application Docker Image (orcidhub/app) is packaged with:

  • CentOS 7

  • Apache 2.4

  • Python 3.6

  • mod_wsgi (Pythgon/WSGI Apache module)

  • psycopg2 (native PostgreSQL Python DB-API 2.0 driver)

  • PyPI packages necessary for the application


  1. Install docker following the instruction at

  2. Install git and docker-compose: sudo apt install -y git docker-compose

  3. Add your user to the docker user group:

  4. And configure Docker to start on boot:

  5. Clone the project repository: git clone

  6. Change the current directory: cd NZ-ORCID-Hub

  7. Create the environment configuration file .env from .env.sample

  8. Set up environment variables UID and GID: export GID=$(id -g) UID

  9. Generate SSL the server key and a self signed certificata in .keys directory, e.g., cd .keys; ../gen-keys/; cd -

  10. Create PostgreSQL and redis instance folders: mkdir -p pgdata data/redis

  11. Run application containers: docker-compose up -d

  12. Register a Hub administrator, e.g., docker-compose exec app ./ cradmin -V (more options available: docker-compose exec app ./ cradmin –help)

  13. Enable sendmail, see Sendmail configuration

  14. Open the Hub Application in a browser using http://localhost.

If successful, you will have five containers running: nzorcidhub_worker_1, nzorcidhub_scheduler_1, nzorcidhub_app_1, nzorcidhub_redis_1, and nzorcidhub_db_1. App is the core Hub code, and the process to connect to for users. Redis, worker, and scheduler are the processes that managing the Hub’s task queue.

Every subsequent restart can be achieved with:

export GID=$(id -g) UID
docker-compose up -d

from within the source directory. If/when you wish to stop the Hub simply:

docker-compose down

Environment Variables

The application image uses several environment variables which are easy to miss. These variables should be set up for the specific runtime environment with the configuration specified in the .env file:




The runtime environment name (default: test)


Your Identity Provider domain name (default:


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


Shibboleth SAML 2.0 meta data provider URI [NativeSPMetadataProvider]( (default:


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


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


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


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


PostgreSQL password


The port on which PostgreSQL should be mapped to (should be unique) (default: 5432)


Hub secret key for data encryption


Sentry DSN (optional)


2 first octets (it should be unique for each environment run on the same machine), (default: 172.33)

Common problems

Error at SSL creation in setup

If you get the error “unable to write random state” at SSL certificate creation, you need to get ownership of ~/.rnd (which is likely owned by root). The easiest way to fix is to delete this file:

sudo rm ~/.rnd

and retry this step.

Can only docker/docker-compose with sudo

If docker-compose up fails the most likely cause is that you need to add the current user to the docker group.

sudo usermod -aG docker {your-user}

Once done, log out/in or restart to have this change take effect.

NB this is likely unsuitable for any production instance as the user will now be able to run containers to obtain root privileges. See:

Services report error(s) during docker-compose up

If docker-compose up fails at nzorcidhub_app_1, e.g., with “ERROR: for nzorcidhub_app_1 cannot start service app…Bind for failed: port is already allocated” because you have other services using these ports, alternative ports for the Hub instance can be set in .env.




alternative http port (default: 80)


alternative https port (default: 443)

If it’s just a remnant of an earlier docker-compose pull or similar, a restart or killing the docker-proxy process will clear this isssue, e.g.,

sudo lsof -i:433 | grep LISTEN
sudo kill {PID identified above}

If docker-compose up fails at nzorcidhub_db_1, you’ve likely forgotten to precede this command with the necessary export GID=$(id -g) UID.

Need more help

For more guidance on troubleshooting docker see Troubleshooting