Skip to content

Latest commit

 

History

History
227 lines (146 loc) · 8.74 KB

DEPLOYING.md

File metadata and controls

227 lines (146 loc) · 8.74 KB
Raw

Search Aggregation Engine Deployment Guide

Configuration

There are several files that allow for configuration:

  • The .env file.
  • The src/main/resources/application.yml file.
  • The build/appConfig.js.template file.

Most settings can and should be configured using the .env file when using docker-compose. In other cases, either passing environment variables to docker, manually exporting environment variables, or directly editing the configuration files may be necessary.

The src/main/resources/application.yml file can be configured through environment variables. Consult the Spring Documentation in regards to this.

The build/appConfig.js.template has limited support for environment variables but for those that are exposed may be altered using the .env file.

In addition to the configuration file, the following build arguments are available for customization for a Docker utilizing the solr/Dockerfile file:

  • SOLR_USER: A user name that solr runs as (this should almost always be set to solr).
  • MAIN_CORE: The primary SOLR core (this must always be defined).
  • EXTRA_CORES: Additional (space separated) SOLR cores to use (this may be empty).

Example building and running SOLR using EXTRA_CORES:

cd solr/
docker image build --no-cache --build-arg=EXTRA_CORES="extra_core-1 extra_core-2" -t local_solr .
docker run -it local_solr

Authorization

By default, SAGE is configured to support e-mail based registration and authorization using passwords using the emailRegistration setting. There is generally no need to change this.

SAGE can also be configured to use Weaver Authentication using the weaverAuth setting. The Weaver Authentication is an external authorization abstraction which brings additional identity provider support into the platform.

Advanced Authorization

The SAGE UI's appConfig object has an authStrategies property that accepts a list of strings representing the active auth strategies:

  'authStrategies': ['emailRegistration'],

The SAGE UI displays different login prompts and exhibits certain behaviors based on the authStrategies property.

When emailRegistration is active, the appLoginController, an extension of Weaver's LoginController is used. When weaverAuth is active, a controller provided by Weaver UI Core is used.

If you are using an auth service other than SAGE's built in service, you will need to provide its url using the 'authService' property, also part of the appConfig object:

It's most common to choose a single authentication strategy, but it is technically possible to support multiple strategies simultaneously by listing each entry separated by commas.

Mocked Authorization

The SAGE service can also be run with a development only profile that provides mock auth credentials.

This is activated by choosing mock-token-provider as the active profile in application.yml (or via an appropriate environment variable):

spring.profiles.active: mock-token-provider

Customizing Authorization Strategies

The emailRegistration strategy can be customized by altering the AuthController.java class.

It is also possible to substitute this class for a different class by having that class extend edu.tamu.weaver.auth.controller.WeaverAuthController.

You will also need to remove the @RestController and @RequestMapping("/auth") annotations from AuthController and add them to your new class. Under the hood, the Weaver Framework uses the "/auth" API endpoint to pass auth tokens to client applications.

Production Deployments

For production deployments, deploy using docker-compose. This is the recommended method of deployment for production systems.

Perform the following steps to deploy (with an existing Solr index):

git clone https://github.com/TAMULib/SAGE.git SAGE

cd SAGE/

cp example.env .env

# Make any changes to the .env file before here (see the configuration sections).
docker-compose up

If an existing Solr index is not available, then perform the following after copying the .env file.

cd SAGE/solr
docker build -t sage/solr .
docker run -p 8983:8983 -it sage/solr

* Note: when using the same terminal to start both the Solr index and SAGE, the -d parameter may be useful to detach when running (docker run -p 8983:8983 -dit sage/solr).

The development deployment can also use docker-compose in the same way.

Development Deployment using Docker

To manually use docker rather than docker-compose, run the following:

docker image build -t project .
docker run -it project

* Note: -t project and -it project may be changed to another tag name as desired, such as -t developing_on_this and -it developing_on_this.
** Note: An additional step may be required, such as deploying alongside a Weaver UI Core instance using Verdaccio.

To deploy alongside a Weaver UI Core instance using Verdaccio, do the following before deploying:

cd Weaver-UI-Core
docker image build -t weaver-ui .
docker run -it weaver-ui

The host system affects the network being used and is different from Windows to Mac to Linux.

  • The --network= argument may be needed to assist with this, such as --network=weaver.
  • The --build-arg may be needed to use the appropriate NPM registry settings, such as --build-arg=NPM_REGISTRY="docker-linux".
  • More network related changes may be required, so please consult the appropriate Docker documentation.

Development Deployment using NPM and Maven

Manual deployment can be summed up by running:

NPM

npm install
npm run build
npm run start

Maven

mvn clean spring-boot:run

Those steps are a great way to start but they also fail to explain the customization that is often needed. There are multiple ways to further configure this for deployment to better meet the desired requirements.

It is highly recommended only to perform manual installation when developing. For production deployment, please use either the docker-compose method or the Docker method above.

Directly Configuring the dist/appConfig.js File

This method of configuration works by altering the built distribution configuration file. This file is deleted every time either npm run build or npm run clean are run. But in the event that a quick and manual change is needed, this is the simplest way to do so.

With this in mind, the deployment steps now look like:

npm install
npm run build
dist/appConfig.js
npm run start

* Remember, changes to dist/appConfig.js are lost every time npm run build is run.

Directly Configuring the .wvr/build-config.js Build File

This method of configuration is only recommended for advanced uses but is otherwise not recommended. The advantage of this method of configuration is that of preserving the changes between build or clean commands. There is only a small section that should be changed.

The .wvr/build-config.js file has only a single section of interest and might look something like this:

    {
      from: './build/appConfig.js.template',
      to: './appConfig.js',
      transform(content) {
        return content
          .toString()
          .replace('${AUTH_STRATEGY}', 'weaverAuth')
          .replace('${AUTH_SERVICE_URL}', 'https://labs.library.tamu.edu/auth/2x')
          .replace('${STOMP_DEBUG}', 'false')
          .replace('${AVALON_URL}', 'avalon-pre.library.tamu.edu:443');
      },
    },

In the above example snippet, only the lines containing '${AUTH_STRATEGY}', '${AUTH_SERVICE_URL}', '${STOMP_DEBUG}', and '${AVALON_URL}' should be changed. For example 'https://labs.library.tamu.edu/auth/2x' could be changed to 'https://labs.library.tamu.edu:8443/auth/2x' (changing the port number from 443 to 8443).

Once this is done all of the steps from Development Deployment using NPM and Maven above can be followed.