Commons

The Commons is designed to publish information about digital projects and collections that are maintained within institutional repositories like DSpace, Contentdm, and Hydra or that exist independently as unique, standalone projects like Omeka exhibits and public websites. The Commons provides integration with repository services through shared authentication and authorization and targeted search capability.

The project uses Angular, ngrx, and Angular Material. The Angular-CLI and WebPack are used to develop, test, and build. The project is configured to support server-side rendering using Angular Universal with Node.js and Express. Client and server code is written in Typescript.

The Commons relies on the Tagger-2 public API for data. The Commons is integrated with the dspace-client project for single sign on and automatic login. Passport middleware is used for CAS authentication. (Other authentication services can be used by installing and configuring the required Passport authentication strategy. See server/config/auth-config.ts). Authentication requires information provided in separate credentials.js files (described below).

Redis is used as the session store and is required by the production environment.

Configuration

The Commons is designed to use with the Tagger-2 REST API. You will need that project running with a production or development server before starting.

For server deployment you need to create two configuration files in your home directory (Mac or Windows): ~/etc/commons-dev/credentials.js and ~/etc/commons-prod/credentials.js. Edit the files, providing the following information as appropriate for your development and production environments:

'use strict';

var credentials = {

  logLevel: 'info',
  apiHost: 'https://host.domain.edu',
  serverBaseURL: 'https://host.domain.edu',
  ssoBaseURL: 'https://host.domain.edu/idp/profile/cas',
  validateURL: '/serviceValidate',
  rootPath: '/',
  domain: 'domain.edu',
  authPath: '/com-auth',
  authCheck: '/com-check',
  nodeEnv: 'production',
  redisPort: 6379 // used only in production

};

module.exports = credentials;

In the client, the Angular CLI is configured to recognize development, test and production environments and replace configuration files as needed.

Development

To run the Commons client without Universal server-side rendering, use npm run start:dev.

To work with server-side rendering in development mode, use npm run build:development:ssr and npm run serve:ssr.

Tests

For unit tests, use npm run test.

Production

To build for production, use npm run build:production:ssr and copy the resulting ./dist directory to the production host.

Production Requirements

Session management requires Redis for use as the session store. The redis port is configurable in credentials.js.

(In development we rely on Passport sessions and therefore no session store is needed. But you might not be able to test authentication logic in Universal mode.)

Docker

(Needs update)

At the moment, the docker image is experimental and not used in our production setting. But here are a few things to know.

To use Docker, you will first need to install it on your machine.

A DockerFile is included in the project.

Before working with Docker, be sure to first build the project with npm run build:production:ssr.

Next, to build a docker image from the latest production build, execute docker build -t <name>/<tag>:latest ., substituting real values for the <name> and <tag> placeholders shown here. You can push this image to DockerHub (or elsewhere) if you have an account.

To pull the existing image from DockerHub, use docker pull mspalti/commons, or pull your own DockerHub image if you have one.

If all is proper, on the production host you should be able to start the container with this command: docker run -v /etc/commons-2.0:/etc/commons-2.0 -p 3000:3000. (Details may vary.)

It should be possible to preview the container on your development machine if you:

1. Install and run Tagger-2 on your local machine.
2. Modify the src/client/app/environments/environment.prod file accordingly.
3. Build the project with npm run build:development:ssr
4. Build the docker image with docker build -t <name>/<tag>:latest .
5. Start the docker image with docker run -v <home>/etc/commons:/etc/commons-2.0 -p 3000:3000 where <home> is your local home directory.

Further Help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.