The Global Research and Education Network (GREN) is a “network of networks” that links great minds to each other, and to technologies, research facilities, and data, enabling global research collaborations and education support.
The GREN Map is a database of this connectivity, to be used for visualizing it in both static and interactive displays. It consists of a hierarchical distributed database: each Research and Education Network (REN) will maintain a database node of their own, and also aggregate the data from nodes for the smaller networks that it connects, on a regular polling interval. Ultimately, data will percolate up to a central node for the entire globe.
This repository provides the code for an instance representing a single node in the hierarchy described above.
This container requires Docker and Docker Compose.
Production deployment of this software requires a Shibboleth-based single sign-on identity provider (“IdP”) to authenticate users. For local development or evaluation purposes, a local IdP container (included) may be used. The Quick Start instructions below include this IdP container.
This Quick Start details how to bootstrap this application for evaluation or development.
Production deployment instructions and examples are found in a separate repository. Contact the application developers for more information if required.
After pulling the code from the repository, the first step is to create an environment file that will affect how the containers are configured. There are some examples in the repository to serve as starting points. Copy the file - env/env_example.dev to a new file - env/.env.dev and replace/insert values for the keys listed below with your own.
python3 -c "import secrets; print(secrets.token_urlsafe(50))"
Note the following directories in the repository’s root:
Follow the “env_example” file in the project root to create a local “.env” file in the project root directory. Set up the host name and port for MAP1.
MAP1_HOST_NAME=map1.example.com
MAP1_HOST_PORT=8443
If evaluation or development requires multiple database nodes running simultaneously, to simulate interconnection & polling, configure additional nodes by incrementing the number after MAP, suc as “MAP2”, “MAP3”, etc.:
MAP2_HOST_NAME=map2.example.com
MAP2_HOST_PORT=9002
...
Ensure all host names provided above are also included in the “DJANGO_ALLOWED_HOSTS” item in the relevant file under the ‘env’ directory, for example, ‘env/.env.dev’, like:
DJANGO_ALLOWED_HOSTS=localhost app 127.0.0.1 [::1] websp websp1 websp2 host.docker.internal map1.example.com map2.example.com
Set up the admin password for LDAP in “.env” file, like:
LDAPPWD=ChangePassword
Set up a host name for the IdP in “.env” file, like
IDP_HOST_NAME=idp.example.org
To use the Embedded Discovery Service(EDS) for development or production, add/uncomment the following line in the root “.env” file.
IDP_SSO='<SSO discoveryProtocol="SAMLDS" discoveryURL="https://__MAP_HOST_NAME__:__MAP_HOST_PORT__/shibboleth-ds/index.html">SAML2 SAML1</SSO>'
Add the MAPs’ and IdP’s host names to your computer’s “/etc/hosts”, like:
127.0.0.1 map1.example.com map2.example.com idp.example.org
From the project root directory, run the following script to generate all the needed configuration files for one IdP and one GREN Map DB Node:
./config_sso.sh
Or run with “-m
./config_sso.sh -m 2
A Django user is automatically created every time a new user logs in through Shibboleth. The user’s EPPN will be used as the Django username. Email, first name, and last name will be auto-filled if possible. (They will not overwrite existing values if the user is created ahead of a Shibbolet login.)
At least one admin user should be pre-configured if possible. Add known desired admin users’ EPPNs, space-delimited, to environment files under “env/” folder (for example, “env/.env.prod”, “env/.env.dev” …)
ADMIN_EPPNS=testuser1@example.org testuser2@example.org
Once the application has started, an admin user can add more admin users to a DB Node by assigning both “Staff” and “Superuser” permissions to existing Django users, or new users can be pre-created with their EPPNs as their usernames.
Run two commands to start the DB Node and IdP separately:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
docker-compose -f docker-compose.idp.yml up -d --build
Or run in one command to start them together:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.idp.yml up --build
To start a second DB Node, if applicable:
docker-compose -f docker-compose.yml -f docker-compose.dev2.yml -p gren2 up -d
The container build process might take several minutes to build. Run docker ps to check the containers’ statuses. Wait for all the containers become “healthy” (not “health: starting”), then open a browser (private window suggested) to access the GREN Map DB Node.
Container build may be slow on Apple Silicon by default. To decrease build times:
# Environment variable for docker build
#DOCKER_DEFAULT_PLATFORM=linux/amd64
DOCKER_DEFAULT_PLATFORM=linux/arm64
URLs for the first DB Node server:
https://map1.example.com:8443https://${MAP1_HOST_NAME}:${MAP1_HOST_PORT}Access a second MAP server at:
https://${MAP2_HOST_NAME}:${MAP2_HOST_PORT} (for example: https://map2.example.com:9002)
Inserting REN data into this database can be done manually or by importing a file in GRENML format.
The node also supports import of a Excel spreadsheet in a particular template, via GRENML in the background; see https://github.com/grenmap/GRENML/blob/main/docs/Sample%20Conversion%20Spreadsheet/GREN_data.v1_0.xlsx for this template. A Python library for producing GRENML by script, suitable for increased data gathering automation, is available:
pip install grenml
Please see the user guide in the docs/user directory for more information on importing data.
Please find additional documentation for this application in the docs directory.
This project is licenced under the Apache Licence, Version 2.0. Please refer to LICENSE.md for details on the project license.
Please visit the GitHub project page and contact the administrators or developers for contribution guidance, and read CONTRIBUTING.md for details on the process for submitting pull requests.
Please read CODE_OF_CONDUCT.md for details on the code of conduct.