Configure third-party components

1. Apache must be compiled with the WebDAV module (mod_dav.so).

2. Modules from Subversion must be properly installed (mod_authz_svn.so and mod_dav_svn.so)

   The following lines must be added into an Apache configuration file into the LoadModule section. This can be the default configuration file httpd.conf ([Apache2_Dir]/conf/httpd.conf), or any other conf file, including a new one you create for the purpose. Lines:

   LoadModule dav_svn_module modules/mod_dav_svn.so

   LoadModule authz_svn_module modules/mod_authz_svn.so

3. Add the following lines to your httpd.conf:

   <Location /repo>

   DAV svn

   SVNPath "/opt/polarion/data/svn/repo"

   # our access control policy

   AuthzSVNAccessFile "/opt/polarion/data/svn/access"

   # try anonymous access first, resort to real

   # authentication if necessary.

   Satisfy Any

   Require valid-user

   # How to authenticate a user. (NOTE: Polarion does not

   # currently support HTTP Digest access authentication.)

   AuthType Basic

   AuthName "Subversion repository on localhost"

   AuthUserFile "/opt/polarion/data/svn/passwd"

   SVNAutoversioning on

   </Location>

   #polarion specific configuration of apache for svn

   # and maven2 repo

   # Maven 2 shared repository

   <Directory "/opt/polarion/data/shared-maven-repo">

   Options Indexes

   Order allow,deny

   Allow from all

   </Directory>

   Alias /maven2 "/opt/polarion/data/shared-maven-repo"

   Pay attention to the name of repository (/repo) in the first tag (<Location/repo>). It's the name (an alias) of your subversion repository.

   Don't forget to specify the correct paths to the real repository folder in the SVNPath parameter, to the access file in the AuthzSVNAccessFile parameter, and to the passwd file in the AuthUserFile parameter.

   Pay attention to the paths used in the httpd.conf example above. They must be the same as those used by default by the libinstall/default.sh script. This script won't work if different paths are used.

4. Create a file named workers.properties in your Apache server's configuration directory (where the httpd.conf file resides), with the following:

   worker.list=worker1

   worker.worker1.type=ajp13

   worker.worker1.host=127.0.0.1

   worker.worker1.port=8889

   worker.worker1.lbfactor=50

   worker.worker1.cachesize=50

   worker.worker1.cache_timeout=600

   worker.worker1.socket_keepalive=1

   worker.worker1.recycle_timeout=300

5. Create a file named polarion_mounts.properties in your Apache server's configuration directory (where the httpd.conf file resides). Add the following lines:

   /polarion/*=worker1

   /polarion=worker1

   /svnwebclient/*=worker1

   /svnwebclient=worker1

Either the subversion binary (svn) must be on PATH or the javahl libraries must be properly installed.

The configuration requires several files from the JDK.

• The environment variable JDK_HOME must be properly set.

  (Remember to update the JDK_HOME variable in /opt/polarion/etc/config.sh.)

If you allocate too much memory for the Java Virtual Machine (JVM), the operating system will not initialize it. Diagnosing the issue can be difficult because the service simply does not start and no error log is written. On some Linux versions, a message may appear in the console indicating that the Java Virtual Machine could not be initialized, but without indicating the reason.

The amount of memory you can allocate to the JVM depends on what OS you have and how much total memory exists on the computer. The more total memory the more you can allocate to the JVM before the operating system imposes a limit the better.

It's good to update OpenJDK regularly for security reasons, but check the README.html file to ensure that major Java version updates are officially supported by Polarion before updating to them.

Please take the usual steps specific to your distribution.

When updating Java please remember to update variable JDK_HOME in /opt/polarion/etc/config.sh.

The location of PostgreSQL utilities depends on the specific Linux distribution. The command examples below assume that the folder containing PostgreSQL binaries is added to your system PATH variable.

The OS user postgres is normally created as a result of the PostgreSQL installation. To be able to use the psql utility, you must access it as this user.

A) Create the PostgreSQL database storage:

1. Create a folder to store PostgreSQL data and make the postgres user the owner of this folder on Linux. Any location will be fine, as long as the postgres user owns the folder. You can use the following example where the folder for PostgreSQL data is: /opt/polarion/data/postgres-data

   mkdir /opt/polarion/data/postgres-data

   chown postgres:postgres /opt/polarion/data/postgres-data

2. As the postgres user, initialize the database using the initdb command. The syntax differs for PostgreSQL versions, as shown in the following examples, with our /opt/data/postgres-data folder. Use psql --version to check for the version.

   For PostgreSQL version 9.1 and earlier:

   su postgres

   initdb -D /opt/polarion/data/postgres-data -E utf8

   For PostgreSQL versions after 9.1:

   initdb -D /opt/polarion/data/postgres-data -E utf8

   --auth-host=md5

   In some cases, initdb is not available immediately after the installation, and you need to add to your path. You can use the locate command to find the location of psql. If it cannot be found, use the updatedb command and search for it again. More information about initdb can be found at: http://www.postgresql.org/docs/9.4/static/app-initdb.html.

3. Start the PostgreSQL server. Remember that all PostgreSQL utilities must be run on behalf of the postgres system user, and you must initialize the database storage as described in step 2 above prior to running the server for the first time.

   su postgres

   pg_ctl -D /opt/polarion/data/postgres-data -l /opt/polarion/data/postgres-data/log.out -o "-p 5433" start

   (The pg ctl command should be written to a single command line.) You can define additional options, such as the port on which the database should run. Check http://www.postgresql.org/docs/9.4/static/app-pg-ctl.html for an overview of options.

B) Connect to the Root Database of PostgreSQL:

For configuration of Polarion databases, you need to connect to the root database of PostgreSQL postgres using your favorite SQL client, for example Squirrel), or just use PostgreSQL's built in the psql tool.

1. On Linux, the operations with PostgreSQL database must be run on behalf of the postgres user: su postgres

2. Connect to the PostgreSQL postgres root database on behalf of the postgres user (or the database's superuser): psql -p <port> postgres

The syntax for psql is: psql -p <port> -U <user> <database>

Example: psql -p 5433 -U polarion polarion_history

C) Create the Polarion User and the Databases:

Polarion uses two databases, polarion and polarion_history, which will be owned by the polarion user, so the first step is to create the polarion user. To do this, execute the following three SQL statements using your SQL client:

1. Create the polarion user and replace the <your-password> with a password of your choice:

   (The password cannot contain any of the following characters: @, :, \, ', " or leading/trailing spaces.)

   CREATE USER polarion WITH PASSWORD '<your-password>' CREATEROLE;

2. Create the Polarion database:

   CREATE DATABASE polarion OWNER polarion ENCODING 'UTF8';

3. Create the polarion_history database:

   CREATE DATABASE polarion_history OWNER polarion ENCODING 'UTF8';

4. Quit the psql utility using the \q command.

D) Install dblink Extension and PLPGSQL Language:

After you have created the two databases for Polarion, you need to install the DBLink extension on both of them. The DBLink extension is used to enable Lucene queries within SQL queries. Some functions used by Polarion use the PLPGSQL language, which needs to be installed as well.

1. Connect to the polarion database via psql client as postgres database user (or the superuser): psql -p 5433 polarion

2. Create the DBLink extension.

   1. If your PostgreSQL version is 9.1 or later, just execute the following SQL command: CREATE EXTENSION dblink;

   2. If your PostgreSQL version is 9.0 or earlier, use the psql tool to set up the extension using the following command:

      - If not connected to psql: psql -p <port> polarion -f dblink.sql

      - If already connected: \i dblink.sql;

      The dblink.sql file was installed during your installation of PostgreSQL. The location depends on your Linux distribution. You can use the locate command to find it.

3. To verify that the dblink extension was successfully installed, execute this SQL query in your database client:

   SELECT p.proname

   FROM pg_catalog.pg_namespace n

   JOIN pg_catalog.pg_proc p

   ON p.pronamespace = n.oid

   WHERE n.nspname = 'public';

   It should return rows containing db_link as a prefix.

4. Install the PLPGSQL language by executing the following SQL command:

   CREATE LANGUAGE plpgsql;

5. Quit the psql utility (\q) and repeat the above steps for the polarion_history database.

6. If you did not run the initialization of the database with --auth-host=md5, open [PG_DATA]/pg_hba.conf and change all the host entries with trust to md5, then restart PostgreSQL. (In our examples, [PG_DATA] was /opt/polarion/data/postgres-data (the location on which the database was initialized).

E) Optimize the PostgreSQL Database:

Optimization is the same as described for automated installation.

(See After installation: optimizing the PostgreSQL database.)

F) Configure Polarion to use PostgreSQL database:

Add the following property to the polarion.properties system configuration file:

com.polarion.platform.internalPG=polarion:<password>@<hostname>:<port>

For example:

com.polarion.platform.internalPG=polarion:polarion@localhost:5433

If you have the polarion and polarion_history databases running on different servers, you can use these two properties rather than the above property:

com.polarion.platform.sql.internalDB.head.url=jdbc:postgresql:

//<hostname>:<port>/polarion?user=<userName>&password=<password>

com.polarion.platform.sql.internalDB.historical.url=jdbc:postgresql:

//<hostname>:<port>/polarion_history?user=<userName>&password=<password>

After you have set the system properties, reindex your Polarion installation so that the PostgreSQL database will be populated. Using any SQL client after the reindex, you should see the database filled in the polarion schema.

G) (Optional) Allow remote connections to the PostgreSQL server:

By default the PostgreSQL database is only available on localhost after a fresh install. If you need to have access from outside the host machine, please follow these steps to allow remote access:

1. Change the listener addresses in the postgresql.conf file. This file can be found in the PostgreSQL data folder, the one you have defined under Starting/Stopping PostgreSQL. In this file, change: #listen_addresses='localhost' to listen_addresses='*'

2. In the same folder, you will find the pg_hba.conf file. Open it in a text editor and add the following line: host all all 0.0.0.0/0 md5

   Warning:

   If you allow for external connections to the database, an external user has blanket access to the entire database content and effectively to all Polarion data - all projects, the HEAD revision as well as history. There is no further access control. All Polarion user names will also be visible. (Polarion user passwords will not be visible as those are not stored in a database or SVN.) Access is read-only.

   Administrators are advised to consider carefully before opening database access in a system in use on a production level.

H) Check Shared Buffers Configuration

Check that the value of the shared_buffers parameter in postgresql.conf does not exceed the available shared memory configured by the SHMMAX kernel parameter .