FOLIO Documentation – Install FOLIO

Docs: Host names

Mon, 01 Jan 0001 00:00:00 +0000

Choosing the host names of front-end and back-end has implications on deployment, security and performance.

The frond-end host serves the content to be displayed in the browser. The back-end exposes Okapi and the APIs of the back-end modules.

Same host name

Front-end and back-end can be provided on the same host so that they use the same host name, the back-end is served on a special URL path.

Existing example:

Advantages:

Most secure solution. Using a single host name allows to use the most restrictive configuration regarding cross-origin resource sharing (CORS) and cross-site request forgery (CSRF).
Most simple security configuration.

Disadvantages:

Requires a path based proxy. Example snippet for nginx:

        # WARNING: location requires a trailing slash
        location /okapi/ {
                # WARNING: proxy_cookie_path requires a trailing slash
                proxy_cookie_path / /okapi/;
                # WARNING: proxy_pass requires a trailing slash
                proxy_pass http://127.0.0.1:9130/;
                proxy_redirect default;
        }

        location / {
                root /var/www/tenanta;
                try_files $uri /index.html;
        }

Using a content delivery network (CDN) might require different cache configurations for front-end and back-end URL paths.

Two host names on same site

Some FOLIO deployments use different host names for font-end and back-end, and the host names belong to the same site. Example for site folio.org:

“Same site” has a special meaning, learn more at https://web.dev/samesite-cookies-explained/ and https://publicsuffix.org/ .

Advantages:

Simple host name based configuration, requires no path based proxy configuration.
Continuously tested on FOLIO’s reference environments.

Disadvantages:

Slower because the browser needs to send extra “preflight” OPTIONS HTTP requests for cross-origin resource sharing (CORS) protection resulting in latency.
Less secure as it requires a configuration that weakens the security restrictions regarding cross-origin resource sharing (CORS) and cross-site request forgery (CSRF).

Two host names on different sites

FOLIO doesn’t support running front-end and back-end on host names that belong to different sites.

Fictional example:

This requires removing security restrictions regarding cross-origin resource sharing (CORS) and cross-site request forgery (CSRF) and likely violates security rules required by law or policy.

FOLIO prevents this configuration for the most security sensitive module, the single-sign-on (SSO) module mod-login-saml.

Docs: Kubernetes example

Mon, 01 Jan 0001 00:00:00 +0000

The Rancher/Kubernetes solution allows for the addition of new tenants and hardware resources on demand. It is ideal if you need to scale-up your FOLIO instance in the future. This guide describes a Rancher/Kubernetes installation.

Deployment environments

FOLIO is a system built on micro-services. It is designed to be a multi-tenant cloud environment. Having said that, some institutions will also choose to deploy FOLIO on premise. The community can expect a wide range of deployment environments and mechanisms. This guide will describe some of the issues that need to be understood in a Rancher/Kubernetes environment and the choices around those issues. We will also label what are felt to be best practices when possible.

Public cloud vs on premise

A production ready FOLIO deployment will need adequate infrastructure for reliable service. The institution will have to decide where and how to deploy FOLIO. The public cloud vs on premise choice will define sets of alternatives for technology and tooling. For example, if a site chooses to deploy in AWS then it will have a set of tooling and technology that are not available on premise. It will also possibly use proprietary solutions such as RDS. The deployment process will be adapted for the specifics of each organization.

Virtual vs physical

Virtualization has become a common practice in data centers due to the convenience of managing virtual environments. However, some institutions may prefer physical servers for various reasons. The virtual vs physical choice need not be dictated by the cloud vs on premise choice. For example, you can run VMware in AWS. Fortunately, the deployment process for a FOLIO instance is practically the same in both scenarios.

Database considerations

FOLIO has been designed and developed with PostgreSQL as the default database engine. Although using Postgres isn’t mandatory, it is recommended for the vast majority of use cases. The main considerations with PostgreSQL and FOLIO are:

Use a Cloud service such as Amazon RDS or Amazon Aurora.
Set up a dedicated database server or cluster.
Implement PostgreSQL-as-a-Service using Kubernetes.
Use independent PostgreSQL servers for the components of FOLIO.

These choices will depend on each organization’s needs. However, from the FOLIO deployment perspective you only will need an accessible PostgreSQL service.

Orchestration tools

There are many orchestration tools for both on premise and cloud solutions, including but not limited to: Kubernetes, OpenShift, Docker Swarm or ECS (Amazon). In theory, you can use any of them to deploy FOLIO due to its microservice architecture, but the Rancher/Kubernetes solution is the most common within the FOLIO community and therefore it will be covered in this manual.

Deploy Rancher server

You will need a Rancher server for managing the Kubernetes cluster for FOLIO. This server should be accessible for all of the Kubernetes nodes in your cluster. If you are using AWS, you will need to configure a VPC, subnets and route tables.

A sample configuration and deployment procedure can be found at https://github.com/folio-org/folio-install/tree/master/alternative-install/kubernetes-rancher/TAMU.

Docs: Customizations

Mon, 01 Jan 0001 00:00:00 +0000

Branding Stripes

Stripes has some basic branding configurations that are applied during the build process. In the file stripes.config.js, you can configure the logo and favicon of the tenant, and the CSS style of the main navigation and the login. These parameters can be set under the branding key at the end of the file. You can add the new images in the folder tenant-assets and link to them in the configuration file.

In the config key you can set the welcomeMessage shown after login, the platformName that is appended to the page title and is shown in browser tabs and browser bookmarks. Add a header with additional information to the Settings > Software versions page via the aboutInstallVersion and aboutInstallDate properties, the latter is automatically converted into the locale of the user opening the page, for example 10/30/2023 or 30.10.2023.

Take into account that these changes will take effect after you build the webpack for Stripes.

Example stripes.config.js customization:

module.exports = {
  config: {
    welcomeMessage: 'Welcome, the Future Of Libraries Is OPEN!',
    platformName: 'FOLIO',
    aboutInstallVersion: 'Poppy Hot Fix #2',
    aboutInstallDate: '2023-10-30',
  },
  branding: {
    logo: {
      src: './tenant-assets/my-logo.png',
      alt: 'my alt text',
    },
    favicon: {
      src: './tenant-assets/my-favicon.ico',
    },
    style: {
      mainNav: {
        backgroundColor: "#036",
      },
      login: {
        backgroundColor: "#fcb",
      },
    },
  },
}

There are other stripes.config.js properties.

Okapi security

Make sure that you have secured Okapi before publishing it to the Internet. If you do not configure a super-tenant user and password for Okapi API, any user on the net could run privileged requests. The process of securing Okapi is performed with the secure-supertenant script and it is explained in the Single server deployment guides.

Additionally, it is recommended that you configure SSL certificates for Okapi in order to prevent data being sent as plain text over the Internet. Okapi does not have native HTTPS support, but you can set up a reverse proxy (e.g NGINX) that receives HTTPS requests and forwards them to Okapi. You can find more information about HTTPS on NGINX here. Also, if you are using an Ingress in Kubernetes, you can configure SSL certificates using Rancher. For more information on this process check here.

Email configuration

The module mod-email provides the role of delivering messages using SMTP server to send emails in FOLIO. It is used for sending notifications and restarting user passwords.

The mod-email module uses mod-configuration to get connection parameters. A detailed list of parameters can be found in the documentation of the module. The required configuration options are the following:

EMAIL_SMTP_HOST
EMAIL_SMTP_PORT
EMAIL_USERNAME
EMAIL_PASSWORD
EMAIL_FROM
EMAIL_SMTP_SSL

These parameters should be set in Okapi through POST requests using the name of the module: SMTP_SERVER. For example, the host configuration would look like this.

curl -X POST \
 http://localhost:9130/configurations/entries \
 -H 'Content-Type: application/json' \
 -H 'X-Okapi-Tenant: <tenant>' \
 -H 'x-okapi-token: <token>' \
 -d
   '{
     "module": "SMTP_SERVER",
     "configName": "smtp",
     "code": "EMAIL_SMTP_HOST",
     "description": "server smtp host",
     "default": true,
     "enabled": true,
     "value": "smtp.googlemail.com"
   }'

Take into account that this configuration is performed on a per tenant basis and the tenant ID is defined in the X-Okapi-Tenant header. Also, you have to be logged in as the superuser of the tenant and provide the access token in the header x-okapi-token. You can find an example of a login request here.

Once you have configured the mod-email module, you should configure other modules related to the email configuration. You should configure the users module and edge-sip2. You can find a Bash script that could be used to automate this process here. Make sure that you replace all of the environment variables required for the script.

Alternatively, if you deployed FOLIO on a Kubernetes cluster, you can create a Kubernetes Job for this task. This docker project https://github.com/folio-org/folio-install/tree/kube-rancher/alternative-install/kubernetes-rancher/TAMU/deploy-jobs/create-email can be built, pushed to the image registry and executed on the cluster similarly to other scripts mentioned in the Kubernetes deployment section.

Install and serve edge modules

These instructions have been written for a single server environment in which Okapi is running on localhost:9130.

If you do a test installation of FOLIO, you do not need to install any edge modules at all. Install an edge module in a test environment only if you want to test the edge module.

The Edge modules bridge the gap between some specific third-party services and FOLIO (e.g. RTAC, OAI-PMH). In these FOLIO reference environments, the set of edge services are accessed via port 8000. In this example, the edge-oai-pmh will be installed.

You can find more information about the Edge modules of FOLIO in the Wiki https://wiki.folio.org/display/FOLIOtips/Edge+APIs.

Create institutional user. An institutional user must be created with appropriate permissions to use the edge module. You can use the included create-user.py to create a user and assign permissions.

python3 create-user.py -u instuser -p instpass \
    --permissions oai-pmh.all --tenant diku \
    --admin-user diku_admin --admin-password admin

If you need to specify an Okapi instance running somewhere other than http://localhost:9130, then add the –okapi-url flag to pass a different url. If more than one permission set needs to be assigned, then use a comma delimited list, i.e. –permissions edge-rtac.all,edge-oai-pmh.all.

The institutional user is created for each tenant for the purposes of edge APIs. The credentials are stored in one of the secure stores and retrieved as needed by the edge API. See more information about secure stores. In this example, a basic EphemeralStore using an ephemeral.properties file which stores credentials in plain text. This is meant for development and demonstration purposes only.

sudo mkdir -p /etc/folio/edge
sudo vi /etc/folio/edge/edge-oai-pmh-ephemeral.properties

The ephemeral properties file should look like this.

secureStore.type=Ephemeral
# a comma separated list of tenants
tenants=diku
#######################################################
# For each tenant, the institutional user password...
#
# Note: this is intended for development purposes only
#######################################################
# format: tenant=username,password
diku=instuser,instpass

Start edge module Docker containers. You will need the version of the edge-modules available on Okapi for the tenant. You can run a CURL request to Okapi and get the version of the edge-oai-pmh module.

curl -s http://localhost:9130/_/proxy/tenants/diku/modules | jq -r '.[].id' | grep 'edge-'

Set up a docker compose file in /etc/folio/edge/docker-compose.yml that defines each edge module that is to be run as a service. The compose file should look like this.

version: '2'
services:
  edge-oai-pmh:
    ports:
      - "9700:8081"
    image: folioorg/edge-oai-pmh:2.2.1
    volumes:
      - /etc/folio/edge:/mnt
    command:
      -"Dokapi_url=http://10.0.2.15:9130"
      -"Dsecure_store_props=/mnt/edge-oai-pmh-ephemeral.properties"
    restart: "always"

Make sure you use the private IP of the server for the Okapi URL.

Start the edge module containers.

cd /etc/folio/edge
sudo docker-compose up -d

Set up NGINX.

Create a new virtual host configuration to proxy the edge modules. This needs to be done inside your Stripes container. Log in to the stripes container, cd into the nginx configuration directory and create a new nginx configuration file there:

docker ps --all | grep stripes
docker exec -it <stripes container id> /bin/sh
cd /etc/nginx/conf.d
edit edge-oai.conf

Insert the following contents into the new file edge-oai.conf:

server {
  listen 8130;
  server_name <YOUR_SERVER_NAME>;
  charset utf-8;
  access_log  /var/log/nginx/oai.access.log  combined;
  location /oai {
    rewrite ^/oai/(.*) /$1 break;
    proxy_pass http://<YOUR_SERVER_NAEM>:9700/;
  }
}

YOUR_SERVER_NAME might be localhost. If you are working inside a Vagrant box, it is 10.0.2.15. Exit the container and then restart the container:

docker restart <stripes container id>

You might also want to modify the Docker file that builds your Stripes container. So you will be able to re-build the container later or on some other machine. Add the file edge-oai.conf (with the contents as above) to the directory $HOME/platform-complete/docker/. Then add a line to the Dockerfile $HOME/platform-complete/docker/Dockerfile:

COPY docker/edge-oai.conf /etc/nginx/conf.d/edge-oai.conf

Commit your changes to a local (or personal or institutional) git repository.

Now, an OAI service is running on http://server:8130/oai .

Follow this procedure to generate the API key for the tenant and institutional user that were configured in the previous sections. Currently, the edge modules are protected through API Keys.

cd ~
git clone https://github.com/folio-org/edge-common.git
cd edge-common
mvn package
java -jar target/edge-common-api-key-utils.jar -g -t diku -u instuser

This will return an API key that must be included in requests to edge modules. With this APIKey, you can test the edge module access. For instance, a test OAI request would look like this.

curl -s "http://localhost:8130/oai?apikey=APIKEY=&verb=Identify"

The specific method to construct a request for an edge module is documented in the developers website: https://dev.folio.org/source-code/map/ or you can refer to the github project of the edge module.