Customization

From Dogtag
Jump to: navigation, search

Overview

Some components of the PKI server can be customized. However, when the PKI packages are upgraded the customized components may not be upgraded automatically. It is the admin's responsibility to ensure that the customized components will continue to work with the new PKI packages. So it is important to determine which components to customize and try to minimize the customization.

Customizing Subsystem Web Application

Each PKI subsystem has a corresponding web application which contains:

  • HTML pages which contains texts, JavaScript codes, page layout, CSS formatting, etc.
  • web.xml which defines servlets, paths, security constraints, etc.
  • links to PKI libraries

The subsystem web applications are deployed using context files located in /etc/pki/pki-tomcat/Catalina/localhost/ca.xml:

<Context docBase="/usr/share/pki/ca/webapps/ca" crossContext="true" allowLinking="true">
    ...
</Context>

The docBase points to the location of the default web application folder in /usr/share/pki.

Copying web application files

There are two ways to customize the web application:

  • deep copy
  • shallow copy

Deep copy

To create a deep copy of the web application, copy the web application folder into the instance's webapps folder:

$ cp -r /usr/share/pki/ca/webapps/ca /var/lib/pki/pki-tomcat/webapps
$ chown -R pkiuser.pkiuser /var/lib/pki/pki-tomcat/webapps/ca

Shallow copy

To create a shallow copy of the web application, create a folder in the instance's webapps folder, copy only the files that need to be customized, then create links for the other files/folders. For example, to customize web.xml:

$ mkdir -p /var/lib/pki/pki-tomcat/webapps/ca
$ cd /var/lib/pki/pki-tomcat/webapps/ca
$ ln -s /usr/share/pki/ca/webapps/ca/* .
$ rm -f WEB-INF
$ mkdir WEB-INF
$ ln -s /usr/share/pki/ca/webapps/ca/WEB-INF/* WEB-INF
$ rm -f WEB-INF/web.xml
$ cp /usr/share/pki/ca/webapps/ca/WEB-INF/web.xml WEB-INF
$ chown -R pkiuser.pkiuser .

Configuring web application context

To use the customized web application, change the docBase in /etc/pki/pki-tomcat/Catalina/localhost/ca.xml to point to the custom web application folder relative from the webapps folder:

<Context docBase="ca" crossContext="true" allowLinking="true">
    ...
</Context>

The change will be effective immediately. There is no need to restart the server.

Removing customized web application

To remove the custom web application simply revert the docBase and delete the custom web application folder:

$ rm -rf /var/lib/pki/pki-tomcat/webapps/ca

Customizing Web UI Theme

The subsystem web applications in the same instance share the same theme which contains:

  • CSS files which determine the global appearance
  • image files including logo, icons, etc.
  • branding properties which determine the page title, logo link, title color, etc.

The Web UI theme is deployed using pki.xml context file in /etc/pki/pki-tomcat/Catalina/localhost:

<Context docBase="/usr/share/pki/common-ui" crossContext="true" allowLinking="true">
    ...
</Context>

The docBase points to the location of the default theme folder in /usr/share/pki.

To customize the theme, copy the default theme folder into a pki folder in the instance's webapps folder:

$ cp -r /usr/share/pki/common-ui /var/lib/pki/pki-tomcat/webapps/pki
$ chown -R pkiuser.pkiuser /var/lib/pki/pki-tomcat/webapps/pki

Then change the docBase to point to the custom theme folder relative from the webapps folder:

<Context docBase="pki" crossContext="true" allowLinking="true">
    ...
</Context>

The change will be effective immediately. There is no need to restart the server.

To remove the custom theme simply revert the docBase and delete the custom theme folder:

$ rm -rf /var/lib/pki/pki-tomcat/webapps/pki

Customizing TPS UI

See TPS Token Lifecycle - Customization.

References