This guide provides instructions for installing ERMrest on a Linux distribution from the Red Hat Linux family. We recommend using a current Fedora release to get a reasonably modern Apache HTTPD which supports the HTTP/2 protocol. Installation on CentOS 7 is similar but requires the additional EPEL repository to add third-party dependencies included in Fedora but missing from CentOS; in this case, your server will only support HTTP/1.1.
In all cases, we recommend using the upstream PostgreSQL binary distribution suitable for your OS, to be sure you have the latest stable database release for better performance.
ERMrest depends on the following prerequisites:
- Currently supported Fedora
- PostgreSQL 10 or above
- WebAuthn
This guide assumes only that you have installed the Fedora Linux distribution.
In this document, commands that begin with #
should be run as root or with
super user privileges (sudo
). Commands that begin with $
may be run as a
normal user.
If you run an enterprise Linux distribution instead of Fedora, you will also need additional third-party software. For CentOS 7, run the following commands to install the EPEL repository.
# rsync -v rsync://mirrors.kernel.org/fedora-epel/7/x86_64/e/epel-release*.rpm .
# dnf install epel-release*.rpm
PostgreSQL must be installed and configured to operate within the SE-Linux access control mechanism. We recommend using the latest stable release, i.e. Postgres 10 at time of writing.
-
Install the PostgreSQL 10 repository.
Check the list of packages for the version of PostgreSQL and your distribution from the list at
http://yum.postgresql.org/
.At time of writing, these are the latest packages for stable Fedora and CentOS, respectively:
# dnf install https://download.postgresql.org/pub/repos/yum/10/fedora/fedora-28-x86_64/pgdg-fedora10-10-4.noarch.rpm
## OR
# dnf install https://download.postgresql.org/pub/repos/yum/10/redhat/rhel-7-x86_64/pgdg-centos10-10-4.noarch.rpm
- Install the required packages. You may first want to uninstall any conflicting packages if you had default PostgreSQL packages installed with your base CentOS installation.
# dnf install policycoreutils-python
# dnf remove postgresql{,-server}
# dnf install postgresql10{,-server,-docs,-contrib}
- Add local labeling rules to SE-Linux since the files are not where CentOS expects them.
# semanage fcontext --add --type postgresql_tmp_t "/tmp/\.s\.PGSQL\.[0-9]+.*"
# semanage fcontext --add --type postgresql_exec_t "/usr/pgsql-[.0-9]+/bin/(initdb|postgres)"
# semanage fcontext --add --type postgresql_log_t "/var/lib/pgsql/[.0-9]+/pgstartup\.log"
# semanage fcontext --add --type postgresql_db_t "/var/lib/pgsql/[.0-9]+/data(/.*)?"
# restorecon -rv /var/lib/pgsql/
# restorecon -rv /usr/pgsql-[.0-9]+
- Initialize and enable the
postgresql
service.
# /usr/pgsql-10/bin/postgresql10-setup initdb
# systemctl enable postgresql-10.service
# systemctl start postgresql-10.service
- Verify that postmaster is running under the right SE-Linux context
postgresql_t
(though process IDs will vary of course).
# ps -Z -U postgres
system_u:system_r:unconfined_service_t:s0 22188 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22189 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22191 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22192 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22193 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22194 ? 00:00:00 postmaster
system_u:system_r:unconfined_service_t:s0 22195 ? 00:00:00 postmaster
- Permit network connections to the database service.
# setsebool -P httpd_can_network_connect_db=1
# dnf install httpd mod_{ssl,wsgi} python3{,-psycopg2,-setuptools,-ply}
Install the web framework
# pip3 install flask
WebAuthn is a library that provides a small extension to the lightweight [web.py] web framework. It must be installed first before installing ERMrest.
- Download WebAuthn.
$ git clone https://github.com/informatics-isi-edu/webauthn.git webauthn
- From the WebAuthn source directory, run the installation and deployment scripts.
# cd webauthn
# make preinstall_centos
# make install
# make deploy
The preinstall_centos
target attempts to install prerequisites
for Red Hat family distributions. System administrators may prefer
to review the Makefile and install packages manually instead.
This will install the WebAuthn Python module under
/usr/local/lib/python3*/site-packages/webauthn2/
. It will also create a
daemon account webauthn
and place a default security config under
~webauthn/webauthn2_config.json
. A new web service will be
enabled under /etc/httpd/conf.d/wsgi_webauthn2.conf
.
After installing the prerequisite, you are ready to install ERMrest.
- Download ERMrest.
$ git clone https://github.com/informatics-isi-edu/ermrest.git ermrest
- From the ERMrest source directory, run the installation script.
# cd ermrest
# make install [PLATFORM=centos7]
The install script:
- installs the ERMrest Python module under
/usr/lib/python3*/site-packages
- installs command-line interface (CLI) tools under
/usr/local/bin
.
Note, the Makefile install target just invokes python3 ./setup.py install
- From the same directory, run the deployment script.
# make deploy [PLATFORM=centos7]
The deployment script:
- runs install target
- prepares service environment (makes ERMrest daemon user, creates directories)
- creates and initializes ERMrest-specific database, owned by daemon user
- creates default Apache httpd integration as
/etc/httpd/conf.d/wsgi_ermrest.conf
. - creates default service config as
/home/ermrest/ermrest_config.json
CentOS notes:
- you may need to uninstall mod_python to use mod_wsgi
- you may need to uncomment
/etc/httpd/conf.d/wsgi.conf
load module.
- Restart the Apache httpd service
# service httpd restart
Changes to code in your working copy can be quickly tested with the following commands.
# cd path/to/ermrest
# make install [PLATFORM=centos7]
# make deploy
# service httpd restart
The install
target updates files under
/usr/local/lib/python3*/site-packages/ermrest
. The deploy
target runs
idempotent deploy processes which MAY upgrade the database schema in
existing catalogs. For small changes to service code, the deploy
target is unnecessary; however, it is safe to always run to be sure
that catalogs are upgraded as necessary to match the newly installed
service code.
You may want to review ermrest_config.json
and
wsgi_ermrest.conf
in the installation location for changes. These are
deployed to /home/ermrest/
and /etc/httpd/conf.d/
, respectively,
during fresh installs but will not overwrite deployed configurations
during an updating install.
Change the following config file to use different authentication modes:
- /home/webauthn/webauthn2_config.json
"sessionids_provider": "webcookie",
"sessionstates_provider": "database",
"clients_provider": "database",
"attributes_provider": "database",
"preauth_provider": "database",
For more details, see a webauthn config example.
The WebAuthn framework allows for pluggable security providers for authenticating clients. The simplest configuration assumes [basic authentication] against an internal database of usernames and passwords and attributes.
- Switch to the
webauthn
user in order to perform the configuration steps.
# su - webauthn
- Setup an administrator account.
$ webauthn2-manage adduser root
$ webauthn2-manage addattr admin
$ webauthn2-manage assign root admin
$ webauthn2-manage passwd root 'your password here'
The admin
attribute has special meaning only if it appears in ACLs
in ~webauthn/webauthn2_config.json
or ~ermrest/ermrest_config.json
.
- Setup a user account.
$ webauthn2-manage adduser myuser
$ webauthn2-manage passwd myuser 'your password here'
A quick sanity check of the above configuration is to login to ERMrest, create a catalog, and read its meta properties. The following commands can be run as any local user.
- Login to ERMrest using an
admin
account previously created withermrest-webauthn-manage
. Do not include the single quotes in the parameter. The following script will create a cookie file namedcookie
.
$ curl -k -c cookie -d username=testuser -d password='your password here' https://$(hostname)/ermrest/authn/session
- Create a catalog.
$ curl -k -b cookie -X POST https://$(hostname)/ermrest/catalog/
- Inspect the catalog metadata. (Readable indentation added here.)
$ curl -k -b cookie -H "Accept: application/json" \
> https://$(hostname)/ermrest/catalog/1
{
"acls": {"owner": ["testuser"]},
"id": "1"
}
- Inspect the catalog schema.
$ curl -k -b cookie -H "Accept: application/json" \
> https://$(hostname)/ermrest/catalog/1/schema
{
"schemas": {
...
}
You will need to edit your firewall rules if you want to access the ERMrest service from remote hosts. There are multiple ways to do this.
https://fedoraproject.org/wiki/How_to_edit_iptables_rules
Normally, you need to expose the HTTPS port (TCP 443) to client machines. Contact your local system administrator if you need help accomplishing this.