Setting Up Vanguard for Production

Welcome!
Introduction
System Requirements
Prepare for Installation
Install Helpful Software
Install the Database Server
Install and Configure Vanguard
Install and Configure Conditional Software

Welcome!

You’re here because you’re interested in running a Vanguard Production System on your own. If that’s the case and you have not yet contacted ▨▨▨▨▨ ▨▨▨▨▨ (▨▨▨▨@us.ibm.com), please do that first to make arrangements.

If you have questions or concerns during installation, you can contact ▨▨▨▨@us.ibm.com.

Available Release Date
vg_2016_iter01 2016-01-18

To update an existing installation, see the updates page.

Introduction

You can install a complete Vanguard system on one computer or distribute the load across computers. These instructions are organized and written such that you can use them in either scenario.

To decide which setup is right for you, review the system requirements below and assess how the hardware you have available can handle your organization’s build and test needs.

If you distribute across computers, each of the following groups of components can exist on its own server:

  • Database.
  • IDWB build, accessibility and link checking (tests output folders).
  • IEHS, IEHSc, and KC can exist in any combination on any number of servers. When a user requests an individual infocenter or KC collection, you (the admin) can specify which server will host it.
  • NL package return processing.

Except for the database server, each of the other servers requires an instance of the Vanguard web application and its software dependencies. The Vanguard web application handles the communication between the server components.

It is recommended that you install the system on fresh clean computers. The Vanguard system has many software dependencies, some of which have PATH entries, and you don’t want some things colliding with others (for example, CMVC has a file command and there is also a Unix file command, which might have been installed with MKSTools or Cygwin). If you don’t have a fresh computer available, read through these instructions first to assess if there might be conflicts. For example, you’ll probably want Vanguard to run on the default web server port 80; Jenkins runs on port 8080.

As you install, you might wonder why the PHP, Apache, and MySQL versions are 32-bit. Vanguard is built on CakePHP Version 1.3, an old version which is not compatible with PHP later than versions 5.3.x. And, well, we haven’t found 64-bit pre-built binaries of PHP 5.3.x, Apache, and MySQL that play together nicely.

System Requirements

Minimum requirements

A rough estimate of what would be required for a standalone system with ~5 projects (200 total build items), 1 KC instance with 5 collections, 5 review ICs, 5 translation and returns projects, and an active queue size of 5 jobs:

  • 64-bit Windows 7
  • 4 processor cores
  • 8 GB RAM
  • 100 GB total disk space (including OS and required apps)

Recommended requirements

To give a general recommendation for a heavy workload production server, it might be overkill, but this is what the ▨▨▨ team provisioned for an all-in-one standalone Vanguard server (that would have enough to backup the primary production system):

  • 64-bit Windows Server 2008 R2 Enterprise
  • Xeon 2.7 GHz processors: 2 x 16 core processors for a total of 32 cores
  • 192 GB RAM
  • 500 GB available RAID 5 disk space

Current Vanguard primary distributed production system

To give you an idea of what resources could be taken up by a large production system, here’s the current resource breakdown for the Vanguard system used by our group:

  • 64-bit Windows Server 2008 R2 Enterprise

  • CPU: 10 concurrent IDWB builds uses 100% of an 8 core Xeon 2.7 GHz processor, then add hits from KC, IC, and MySQL

  • Memory and disk space for the Vanguard web application are minimal, but total space depends on a number of factors:

    • Memory:

      • Each IC uses about 200 MB.
      • Our KC instance uses about 2.5 GB to host about 30 collections x ~3 versions each
      • 10 concurrent IDWB builds take about 2 GB
      • Our MySQL instance takes up about 1.5 GB
    • Disk space: Total disk usage on all our servers (not including OS and app installations):

      • 30 x ~3 KC collections (16 GB)
      • 397 ICs (16 GB)
      • 291 project directories (130 GB)
      • The MySQL database for all those projects, including IDWB build logs (45 GB)
  • The load is distributed across multiple servers:

    • Server 1: All IDWB builds, accessibility and link tests, some IEHS and IEHSc infocenters. 90% of the users hit this primary server for all Vanguard web application work (creating and maintaining projects, infocenters, etc.).
    • Server 2: Hosts KC and the majority of IEHS and IEHSc infocenters
    • Server 3: Hosts the master database and handles NL package return processing
    • Server 4: A backup server that hosts an actively slave-replicated database and IDWB builds should the primary server become bogged down or go offline

Prepare for Installation

Ready? Let’s get started. :O) Follow these steps on each computer where you will install Vanguard or MySQL server.

  1. Create an Administrator user on the server. Log in with that user and use it for every step of the installation.

  2. During this set up, commands need to be entered from an Administrator command window. To prevent from having to enter Cmd-Shift-Enter every time you open a command window, you can set up your default command prompt to always open as Administrator. If you want to do this:

    1. In File Explorer, right-click on your Admin user’s Command Prompt shortcut in: C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Accessories

    2. Click Advanced on the Shortcut tab, check Run as administrator, and save.

  3. Download and install Mozilla Firefox in its default location.

  4. Open this page in Firefox to access remaining links.

  5. Work with your UT/Design L1 support group to request a license for the server host names that will use ID Workbench (those servers that will download from IDCMS and build or create pakpaks). If you do that now, you can continue with installation while you wait.

  6. Create the folder C:\Apps, where most of the software will be installed. The idea is to keep the PATH environment variable as short as possible for command-line apps, since so many apps will be installed and the ID Workbench has a limit on the length of the PATH environment variable. Also, by using the exact same paths specified in this document, you can cut and paste most of the examples, and it makes maintaining and debugging systems a bit easier.

  7. As you follow along, if you want to easily cut and paste certain example code snippets, set a vanguard_setup environment variable to this folder. For example:

    setx vanguard_setup C:\vanguard_setup
    
    Note:

    Here and in future tasks, whenever you run the setx command to set environment variables, it sets it for the system (or current user in this case), but not for the currently open command windows. After you run the setx command, open another command window to continue with other installation and configuration commands.

    Also, important, do not set the PATH environment variable with setx because it will trucate your existing PATH to 1024 characters!

  8. Because we won’t use setx to set the PATH, whenever the instructions say to append to the PATH environment variable, you can quickly access the system properties window by typing sysdm.cpl at a command prompt or the Start Menu search box.

  9. Download and unzip vanguard_setup.zip to become your %vanguard_setup% folder.

  10. Choose values for the following names and save them somewhere.

    ComputerNameValue
    VanguardServer Admin user 
    VanguardServer Admin password 
    DatabaseMySQL root user password 
    Database &
    Vanguard
    MySQL vanguard user password 

Install Helpful Software

This software is optional, but recommended for each Vangaurd computer, including the database server.

  1. Notepad++ - better than Notepad

    Install into C:\Apps\Notepad++. Otherwise, accept the default installation settings.

  2. 7-Zip 64-bit beta - better than Windows archive folders

    Install into C:\Apps\7-Zip. On the Custom Setup page, click Browse to change the directory. Otherwise, accept the default instllation options.

  3. Process Hacker - better than Windows Task Manager, especially when you need to determine which IEHS instance is which.

    • Log into iRAM, Search for Process Hacker (G2GO - IUA - Process Hacker)
    • The installer is in the binaries folder of the downloaded zip.
    • It’s a GUI application only, so you can accept the default location.
    • Might as well select a Full Installation.
    • Creating a desktop icon for all users is helpful.
    • No need to select other options. It’s useful enough as an application that you manually open only when needed. Sometimes Task Manager is useful rather than replacing it with Process Hacker, especially if you’re not yet used to its interface.
  4. HeidiSQL - Highly recommended for database maintenance, whether from the local database server or remotely.

    • Under continuous development, get the latest version by clicking Installer.
    • You can accept the defaults, including the path since it’s a GUI app.

Install the Database Server

In a standalone environment, you install MySQL and the Vanguard database on the same computer as Vanguard and everything else.

Or, you can choose install the database on a separate computer. If you do, then MySQL need only be installed on that computer and none of the other Vanguard computers. Likewise, Vanguard need not be installed on the database server. Note, however, that the database server and the web application server that users will access most often (for builds, tests, and records management) should be close to each other on the network for faster response times. The web application sometimes makes many database hits per page request.

  1. .NET Framework 4.0 - When the popup opens, choose No thanks, continue.

  2. MySQL Community Server 5.5.38 32-bit (from MariaDB archives)
    • Choose Custom. Accept the default selections, but change the path to C:\Apps\MySQL.
    • When the installation wizard finishes, walk through the advertisement wizard, and then launch the MySQL Server Instance Configuration Wizard.
    • Choose:
      • Detailed Configuration. Next
      • Server Machine, if you expect to support over 50 build projects. Next
      • Transactional Database Only. (We use InnoDB.) Next, Next
      • Manual Setting with 100 concurrent connections. Next, Next
      • Standard character set (Latin1) for the default. Next
      • Install as service, and check include Bin in path. Next
      • Enter a root password. Recommend not enabling remote root access or an anonymous account. Next, Execute
  3. Create a user and database both named ▨▨▨▨, and grant the user full access to the database. First start the MySQL CLI:

    mysql -u root -p
    <enter your mysql root user password>
    

    At the mysql> prompt, enter each of these commands:

    CREATE DATABASE `▨▨▨▨`;
    CREATE USER '▨▨▨▨'@'%' IDENTIFIED BY '<your chosen password>';
    GRANT ALL PRIVILEGES ON `▨▨▨▨`.* TO '▨▨▨▨'@'%' WITH GRANT OPTION;
    FLUSH PRIVILEGES;
    \q
    
  4. Strawberry Perl - Get the latest recommended version. 64-bit is okay for perl. Accept the default folder of C:\Strawberry\.

    Perl is used in the next step for configuration. If you are not installing vanguard on the same computer as your database, then proceed to the next step.

    Otherwise, initialize CPAN, and install the XML::Twig module, which is used by Vanguard link checking. The first installation of the CPAN bundle can take up to 20 minutes (or 45 minutes on a wireless connection, if this is a test installation). Be patient.

    perl -MCPAN -e shell
    cpan> install Bundle::CPAN
    cpan> reload cpan
    cpan> install XML::Twig
    
  5. Customize the data SQL file for your installation by running the following script and answering the questions.

    cd %vanguard_setup%
    perl update_mydb.pl
    
  6. Create tables and add initial data into the ▨▨▨▨ database:

    mysql -u▨▨▨▨ -p ▨▨▨▨ < %vanguard_setup%\vanguard_tables.sql
    <enter your ▨▨▨▨ user password>
    mysql -u▨▨▨▨ -p ▨▨▨▨ < %vanguard_setup%\vanguard_data_mydb.sql
    <enter your ▨▨▨▨ user password>
    
  7. Edit the C:\Apps\MySQL\my.ini file. Find [mysqld], and under that label, add the following line (or change to 16M if the value is already listed in the file):

    max_allowed_packet=16M
    

    Stop and restart the server:

    net stop MySQL
    net start MySQL
    

Install and Configure Vanguard

This software is required to run a the base Vanguard web application. Software required to build, package, view information centers and Knowledge Center collections is described later (for example, if you want to distribute the load on multiple servers) and would be installed in addition to the Vanguard web application software described here.

Installing components

  1. Visual C++ 2010 32-bit redistributable - Easy. Download and install.

  2. Visual C++ 2010 64-bit redistributable - Easy. Download and install.

  3. Visual C++ 2008 SP1 32-bit redistributable - Easy. Download and install.

  4. Apache HTTP Server 2.2.x 32-bit from Apache Lounge - Use 32-bit 2.2.x because it is built with VC 9, which PHP 5.3 requires. Scroll down to find the latest 2.2.x version (httpd-2.2.29-win32.zip as of this writing).

    • Unzip the archive into C:\Apps for C:\Apps\Apache2.

    • Install it as a service named Apache2.2 and set the path to its bin folder (httpd -v is used by Vanguard to show the Apache version on the home page):

      C:\Apps\Apache2\bin\httpd -k install -n "Apache2.2"
      
    • Append ;C:\Apps\Apache2\bin to your PATH environment variable. (httpd -v is used by Vanguard to show the Apache version on the home page.)

  5. Now that you have access to the openssl.exe that is provided with Apache, you can use it to create a certificate request so that you can request a certified SSL certificate from the IBM certificate authority.

    Once you request an SSL certificate, you must wait for manager approval. If you do that now, you can continue with installation while you wait. Request and later download a certificate for each server on which you want to run Vanguard.

    Optionally, you can create a self-signed certificate (second set of details below), but users will see a warning from their browser and it’s not as “official”. :O)

    IBMCA-certified certificate details:

    1. Create the Certificate Request. Substitute <host.domainname> with your full host and domain name. For example: ▨▨▨.▨▨▨.ibm.com.

      cd C:\Apps\Apache2\conf
      set OPENSSL_CONF=C:\Apps\Apache2\conf\openssl.cnf
      ..\bin\openssl req -nodes -newkey rsa:2048 -sha256 -keyout <host.domainname>.key -out <host.domainname>.csr
      

      Answer the questions. Below is an example with some values we use.

      Label Value
      Country Name (AU) US
      State or province (S) CA
      Locality Name (L) San Jose
      Organization (O) IBM
      Organization unit (OU) Analytics, UTS
      Common Name (CN) <host.domainname>
      Email Address same as owner of profile below
      Challenge password blank
      Optional company name blank
    2. The result is a private KEY file and CSR (certificate request) file in your Apache configuration folder.

    3. Use the CSR file to request an SSL certificate. Specifically, go to http://▨▨▨.ibm.com/▨▨▨/▨▨▨▨

      1. Create a certificate profile for the server. Use the same values as used in the certificate request. Also, choose the SERVER type and specify the ITSC104 environment that the server is registered as in MAD. (No problem if you choose the wrong value; you’ll get an error and can try a different value.) For the MAD reference, try entering your host.domainname and hopefully it’s already registered and will be found.

      2. From the profile page, Request a certificate by uploading the CSR file, selecting an approver, and selecting SERVER authorization.

      Later, when approved, you’ll download the certificate, which will be used for Apache SSL configuration. For now, continue.

    Self-signed certificate details:

    Do this only if you didn’t request a certificate as described above. You will create the certificate rather than just a request. The syntax is a bit different than the CA-certified certificate, but provide the same answers to the questions as specified above:

    cd C:\Apps\Apache2\conf
    set OPENSSL_CONF=C:\Apps\Apache2\conf\openssl.cnf
    ..\bin\openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -sha256 -keyout <host.domainname>.key -out <host.domainname>.crt
    

    The CRT file is your self-signed certificate. You’ll use this and the .key file (private key) in your Apache SSL configuration later.

  6. PHP 5.3.29 vc9 32-bit thread safe - This is an old version in the archives, but use it because it has been tested with Apache2 and Vanguard. Use the following info as you go through the wizard.

    • Install it into C:\Apps\PHP.
    • Select the Apache 2.2.x Module
    • Apache Configuration Directory C:\Apps\Apache2\conf\. We’ll let PHP add it’s module information to httpd.conf.
    • Select LDAP as an additional extension to the defaults. Verify that Curl, MySQL, MySQLi, PDO>MySQL, and OpenSSL are also selected.
  7. Java 7.1 built by IBM - Get the latest 64-bit 7.1 version. When registering, it’s for personal use, not product use.
    • Change the path, replacing Program Files with Apps: C:\Apps\IBM\Java71.

    • Select Custom and choose both JRE and SDK.

    • Install it as your system java. Let this be your server’s only Java installation. We’ve had problems with multiple java installations, especially with Jenkins.

    • Set the JAVA_HOME environment variable:

      setx JAVA_HOME C:\Apps\IBM\Java71 /M
      
  8. Strawberry Perl - If you did not already install perl on this computer when you installed the database, get the latest recommended version. 64-bit is okay for perl. Accept the default folder of C:\Strawberry\.

    Initialize CPAN, and install the XML::Twig module, which is used by Vanguard link checking:

    perl -MCPAN -e shell
    cpan> install Bundle::CPAN
    cpan> reload cpan
    cpan> install XML::Twig
    

    Note that reloading CPAN takes about 15 minutes (or even 40 minutes if you’re installing Vanguard as a proof-of-concept on your laptop from a home VPN). Be patient.

  9. Apache Ant 1.8.4 - This version has been tested.

    • Unzip the archive into C:\Apps and rename the folder Ant184, resulting in C:\Apps\Ant184.

    • Set the ANT_HOME environment variable:

      setx ANT_HOME C:\Apps\Ant184 /M
      
    • Append ;C:\Apps\Ant184 to your PATH environment variable.

  10. ant-contrib - Go to the latest stable version, download and open the *.bin.zip file and copy the jar file from its lib folder into C:\Apps\Ant184\lib.

  11. Jakarta Commons 3.x library for Ant - Download and open the bin.zip file and copy its jar files into C:\Apps\Ant184\lib.

  12. HttpComponents HttpClient library 4.x for Ant - Download and open the non-OSGi zip file and copy the jar files from its lib folder into C:\Apps\Ant184\lib.

  13. Jenkins - Get the latest Windows native package.
    • Unzip it and run the .msi file.
    • Install it into C:\Apps\Jenkins\.
    • Afterward, it will try to start in a browser. Close the browser for now.
  14. The Vanguard application code. Extract it to the C drive root folder. It will result in a folder named C:\p.

    unzip %vanguard_setup%\p.zip -d C:\
    

    FYI, the p folder is a legacy name to keep the path name as short as possible. It is short for production, there is also a subfolder, C:\p\p, short for projects.

  15. Install Rational Policy Tester single page scanner.

    cd %vanguard_setup%\RPT
    ASESinglePageScannerSetup_8.5FP2.exe
    

    Follow the prompts and install it into C:\Apps\RPTSinglePageScanner.

Configuring components

PHP

Edit the C:\Apps\PHP\PHP.ini file:

  1. Locate extension_dir, make sure it’s uncommented, and set to the ext subdirectory:

    extension_dir = "ext"
    
  2. Find each of the following parameters, uncomment if required, and set as shown:

    error_log=C:\Apps\PHP\php-errors.log
    max_execution_time = 60
    post_max_size = 17M
    upload_max_filesize = 17M
    date.timezone = America/Los_Angeles
    

Apache

  1. If you requested an IBMCA-certified certificate, then when your manager approves the SSL certificate request, go back to http://▨▨▨.ibm.com/▨▨▨/▨▨▨, view your certificates, and under Actions, select CRT File and click the arrow to download cert.crt.

    Rename it to your host.domainname.crt and copy it to the Apache configuration folder where the request and private key are already, resulting in:

    C:\Apps\Apache2\conf\<host.domainname>.crt
    C:\Apps\Apache2\conf\<host.domainname>.csr
    C:\Apps\Apache2\conf\<host.domainname>.key
    
  2. Add the bluepages.cert to the configuration folder for LDAP authentications.

    copy %vanguard_setup%\bluepages.cert C:\Apps\Apache2\conf
    
  3. Edit the C:\Apps\Apache2\conf\httpd.conf file:

    1. Change ServerRoot to your Apache installation directory:

      ServerRoot "C:/Apps/Apache2"
      
    2. Search for LoadModule and uncomment each of the following modules:

      • authnz_ldap_module
      • ldap_module
      • rewrite_module
      • ssl_module
    3. Below where the modules are loaded, add the following entries for bluepages authentication:

      LDAPTrustedGlobalCert CA_BASE64 "C:/p/www/bluepages.cert"
      
    4. Change the ServerAdmin to your email address:

      ServerAdmin <your.email.address>
      
    5. Uncomment and change the ServerName to your server’s host.domainname at port 80:

      ServerName <host.domainnaime>:80
      
    6. Change the DocumentRoot to the vanguard app folder

      DocumentRoot "C:/p/www"
      
    7. Change the <Directory> that’s currently set to htdocs to point to the new DocumentRoot and specify that this directory allow all overrides (instead of None):

      <Directory "C:/p/www">
        ...
        AllowOverride All
        ...
      </Directory>
      
    8. Make the PHP index the first choice in the dir_module.

      <IfModule dir_module>
          DirectoryIndex index.php index.html
      </IfModule>
      
    9. Right after the LogLevel directive outside of any <IfModule/> sections, add JSON and AJAX requests to an environment that you can filter later in the custom log setting.

      SetEnvIf Request_URI "(\.json)$" no_log
      SetEnvIf Request_URI "(\.ajax)$" no_log
      SetEnvIf Request_URI "(\\/jobs\/active)$" no_log
      
    10. Combined logs are nice. In the log_config_module section, comment out the common one and uncomment the combined one. Whichever one you use, add env=!no_log after it to filter the AJAX and JSON hits.

      #CustomLog "logs/access.log" common
      CustomLog "logs/access.log" combined env=!no_log
      
    11. Toward the bottom of the file are other configuration file includes. Uncomment the SSL configuration file include:

      Include conf/extra/httpd-ssl.conf
      
    12. At the very bottom of the httpd.conf file, the PHP installer should have added some lines in the httpd.conf file to point to its module, and it should have added the x-httpd-php mime type to the mime.types file. If it did, great. If not, add the following lines to your httpd.conf file. I’d put it up just below where the other LoadModule statements are.

      LoadModule php5_module "C:/Apps/PHP/php5apache2_2.dll"
      
      <IfModule php5_module>
        PHPIniDir "C:/Apps/PHP"
        AddType application/x-httpd-php .php
        DirectoryIndex index.php index.html
      </IfModule>
      
  4. Edit the C:\Apps\Apache2\conf\extra\httpd-ssl.conf file.

    1. Change SSLSessionCache to the following:

      SSLSessionCache        "shmcb:C:/Apps/Apache2/logs/ssl_scache(512000)"
      
    2. Change the <VirtualHost> opening element to match your host.domainname:

      <VirtualHost <host.domainname>:443>
      
    3. Inside the VirtualHost element, find each of the following directives and set them to the values shown (using your hostname and email address):

      DocumentRoot "C:/p/www"
      ServerName <host.domainname>
      ServerAdmin <your.email.address>
      ErrorLog "C:/Apps/Apache2/logs/error.log"
      TransferLog "C:/Apps/Apache2/logs/access.log"
      SSLProtocol -SSLv2 -SSLv3
      SSLCertificateFile "C:/Apps/Apache2/conf/<host.domainname>.crt"
      SSLCertificateKeyFile "C:/Apps/Apache2/conf/<host.domainname>.key"
      SSLCertificateChainFile "C:/p/www/IBMca.crt"
      CustomLog "C:/Apps/Apache2/logs/ssl_request.log"
      
  5. Test the syntax of the configuration files and correct any errors found:

    C:\Apps\Apache2\bin\httpd -t
    
  6. Configure it to run as the Administrator user that you are logged in as and restart it:

    services.msc
    

    Find Apache2.2 > Properties > Log On > This account > Enter credentials > OK > Start

Vanguard

  1. Edit the C:\p\vgnlv\web\config.php file and change the relevant values for your database:

    $dbcfg = array(
      'driver' => 'mysql',
      'persistent' => false,
      'host' => '<yourdbhostname>',
      'login' => '<yourdbuser>',
      'password' => '<yourdbpass>',
      'database' => '<yourdbname>',
      'port' => '3306'
    );
    
  2. Edit the C:\p\www\app\config\database.php file and change the relevant values for your database:

    var $default = array(
     'driver' => 'mysql',
     'persistent' => false,
     'host' => '<yourdbhostname>',
     'login' => '<yourdbuser>',
     'password' => '<yourdbpass>',
     'database' => '<yourdbname>',
     'port' => '3306'
    );
    
  3. Edit the C:\p\www\app\config\vanguard.php file and change the following values to fit your environment:

    $config['vg.host_name'] = '<yourvanguardhost.domainname>';
    $config['vg.domainsuffix'] = '<domainsuffix>';
    $config['vg.nlv_server'] = '<yournlprocessingserver>;
    $config['vg.product_name'] = '<A Server Title for the Banner>';
    
  4. Edit the C:\p\www\app\config\vanguard_rarelychanged.php file and change the following value to a distribution list for your set of administrators (or to your email address if you’re the only one).

    $config['vg.support_distribution_list'] = '<your support email address>';
    
  5. Enough has been installed to test and see if the Vanguard web application displays. Open http://localhost. It should redirect to https://localhost ask you to log in, register your user ID, and display the vanguard interface.

    Note:

    Vanguard does not store your w3 password. Apache securely sends the credentials to bluepages LDAP for authentication, and when successful, Vanguard checks the users table for the same email address. When an email is matched, Vanguard generates a session for your remaining activity.

Jenkins

  1. Stop jenkins and assign a quarter of your available memory to it, but not more than the maximum of 2 GB.

    net stop jenkins
    perl -pi.bak -e "s/-Xmx(.*?)\s+/-Xmx2g /;" C:\Apps\Jenkins\jenkins.xml
    
  2. Configure it to run as the Administrator user that you are logged in as:

    services.msc
    

    Find Jenkins > Properties > Log On > This account > Enter credentials > OK

    (The reason you run the Jenkins service under a Windows user ID is so that the Filenet.credentials of that Windows User ID is available to Jenkins when it attempts an IDCMS login.)

  3. Run the mkjenkinsjob.pl perl script to easily create the jobs necessary for running vanguard queues for builds, IC & KC posting, health checks, and NL package processing.

    You run the script with various arguments to generate a job folder and associated config.xml file for the job:

    • -d : creates a jenkins job for the default build queue (build server)
    • -h <server> : create a jenkins job for the health checks queue (build server)
    • -i <server> : create a jenkins job for the IC-posting queue (IC-hosting server)
    • -k <server> : create a jenkins job for the KC-posting queue (KC-hosting server)
    • -n <server> : create a jenkins job for the NL package processing queue (NL-processing server)
    • -s <server> : create a jenkins job for the system queue (each server requires at least one)

    For example, if you are running everything on the same server and you want the server to be able to run four builds at a time (the default queue), you would run the script as follows. (The required -x flag provides a distinguishing number for the queue.)

    cd %vanguard_setup%
    mkjenkinsjob.pl -d -x 1
    mkjenkinsjob.pl -d -x 2
    mkjenkinsjob.pl -d -x 3
    mkjenkinsjob.pl -d -x 4
    mkjenkinsjob.pl -h <host.domainname> -x 1
    mkjenkinsjob.pl -h <host.domainname> -x 2
    mkjenkinsjob.pl -i <host.domainname> -x 1
    mkjenkinsjob.pl -i <host.domainname> -x 2
    mkjenkinsjob.pl -k <host.domainname> -x 1
    mkjenkinsjob.pl -k <host.domainname> -x 2
    mkjenkinsjob.pl -n <host.domainname> -x 1
    mkjenkinsjob.pl -s <host.domainname> -x 1
    

    It’s recommended to run at least 3-4 build queues, a couple of health check, IC, and KC queues. But, only one NL package processing queue and one system queue is required. The Analytics Platform vanguard server runs 13 default build queues, one NL packaging queue, and four of each of the other types of queues.

    When you run the script, the jobs are created in %vanguard_setup%\jenkins_jobs. Copy the contents of this folder into the C:\Apps\Jenkins\jobs folders on the servers where these job queues are required.

  4. Open Jenkins and do the initial set up:

    1. Start the Jenkins service.

      net start jenkins
      
    2. Open Jenkins in a browser: http://localhost:8080

    3. SDS requires us to set up security on Jenkins. We use Project-based matrix security. You set up a single admin user. Give the admin user global permissions. And give anonymous users only read access and nothing else. Here is a good write-up on setting up Project-based matrix authorization.

Install and Configure Conditional Software

The rest of the software you choose to install depends on its purpose and on which server it will run. You will need to choose at least one build server, of course, but some software you might not need to install, such as when you need only IDCMS repositories for builds to KC. In such a case, you can skip CMVC, CVS, RTC, and information centers.

On each server that will download source and run builds or create pakpaks

Prerequisite: Install and configure Vanguard, as previously described.

  1. ObjectRexx - Another Green2Go download where the installer is in the binaries folder. Use ooRexx-4.2.0.winX64.exe for a 64-bit OS. The IDWB page says to accept the defaults, so don’t change the path, even though it’s long. The only thing I changed was the path to the editor, Notepad++ instead of Notepad.

  2. Start > Computer > Properties and next to your computer name, click Change settings. On the Computer Name tab, click Change > More and add your domain suffix (for example, ▨▨▨.ibm.com). Leave Change primary DNS suffix when membership changes unchecked.

    REBOOT - Changing the domain should force a reboot, but you must reboot between installing Rexx and the workbench anyway.

  3. ID Workbench - Download the latest Windows Client Package and unzip it to a folder, and run setup.exe.
    • Most likely you’ll choose Custom setup and select only DITA Tools Core and ID Workbench. Vanguard does not require Oxygen, Arbortext, or DITA Architect.
    • When installed, reboot.
    • After rebooting, Start > Search:’Product Information’ and Check for Updates to install all patches and updates.
    • Start > Search:’Plugin install tool’ and install and update any plugins that you think your writers might use.
    • Start > Search:’Configure’: - authenticate with a user ID that has access to all the IDCMS folders that the server will build. For example, the Vanguard development team has a functional intranet user ID that is in the bluegroup that has read access to the parent /IM path and all child folders in IDCMS. - Choose an AIX server to build PDFs.
  4. Set the FILENET_WORK environment variable to src\en.

    setx FILENET_WORK src\en /M
    
  5. If you have CMVC repositories, download and install CMVC and the CMVC CLI:

    1. Download CMVC, unzip it, and run the included CMVCDC_5.0_Win_Installer.EXE file. It will install CMVC in C:\CMVCDC5.0.

    2. Download CMVC CLI, unzip the cmvccli_WIN_5.0_20120330.1301.zip file, and drag the bin folder to C:\CMVCDC5.0. Then, set the following environment variables:

      setx PATH "%PATH%;C:\CMVCDC5.0\bin" /M
      setx CMVC_AUTH_METHOD PW /M
      
    3. Test it by opening a separate command window and attempting to log in. No error message or response indicates a successful login.

      cvmclog -in <your_cmvc_user_id> -family <an_authorized_family>
      

      For example:

      C:\>cmvclog -in utinfra1 -family ▨▨▨@▨▨▨.ibm.com@▨▨▨▨
      
      Enter the cmvc password for login utinfra1 on family ▨▨▨@▨▨▨.ibm.com@▨▨▨▨:
      ********
      
      C:\>
      
  6. If you have RTC repositories, install your repository’s required version of RTC and set up the scmtools command line:

    1. Download RTC into C:\Apps\jazz.

    2. Append ;C:\Apps\jazz\scmtools to your PATH environment variable.

  7. If you have CVS repositories, install cvs and cvsutil from cygwin. Set the CVS password.

    1. Download cygwin (setup-x86_64.exe) and launch it.

    2. Progress through the wizard until you can select packages. Search for the cvs and cvsutil packages, select them, and proceed to install.

    3. Append ;C:\cygwin\bin to the PATH.

    4. Set the CVS password for the user ID used to log in to the CVS repository:

      mkdir C:\cygwin\home\<userID>
      cd /d C:\cygwin\home\<userID>
      cvs -d :pserver:<userID>@<server.domain.address>:/cvsroot login
      
  8. If you have users who build Windows HTMLHelp, get HTMLHelp Workshop 1.3, install it in a folder of your choosing and add the folder to your PATH environment variable, such as C:\Apps\hhc. If you see a message after installation that says a newer version is installed, just ignore it. The message refers to the included viewer component, not the Workshop itself.

  9. If Jenkins is running and if you installed anything in this section that required you to modify your PATH, restart Jenkins so that the new PATH takes effect in the job environment.

On each server to host Eclipse information centers

Prerequisite: Install and configure Vanguard, as previously described.

  1. The Eclipse Help System - Extract the provided zip files into C:\ibm_help. Use this location because it is where the Vanguard database expects the IEHS installations to be when it sets up and interacts with the information centers.

    mkdir C:\ibm_help
    
    unzip %vanguard_setup%\IBM-Help-Win32_3.6.2.1.v20130905-1554.zip -d C:\ibm_help
    unzip %vanguard_setup%\iehs_nlpackage_3.6.2.1.v20130905-1554.zip -d C:\ibm_help
    move C:\ibm_help\ibm_help C:\ibm_help\3.6.2
    
    unzip %vanguard_setup%\IBM-Help-Win32_3.6.2.1.v20130905-1554.zip -d C:\ibm_help
    unzip %vanguard_setup%\iehsc_win_internal_plugin_3.6.2.1.v20130905-1554.zip -d C:\ibm_help
    unzip %vanguard_setup%\iehsc_nlpackage_3.6.2.1.v20130905-1554.zip -d C:\ibm_help
    move C:\ibm_help\ibm_help C:\ibm_help\3.6.2.c_internal
    
  2. Run the Jenkins job queue perl script to create ICJob queues if you haven’t already, to install in Jenkins running on this IC hosting server.

On each server to host KC collections

Prerequisite: Install and configure Vanguard, as previously described.

  1. Follow ▨▨▨▨ ▨▨▨▨’s instructions verbatim to install a KCHosted environment.

  2. Rename C:\KCHOME to C:\KCHosted.

  3. Edit the server.env and kc.properties files by running this little script and specifying the same KC root folder that you specified when you modified the database DML script:

    cd %vanguard_setup%
    update_kcfiles.pl
    
  4. Copy the following files, where <kcroot> is the folder specified in the previous step.

    mkdir C:\KCHosted\<kcroot>
    copy %vanguard_setup%\kc\kc.properties C:\KCHosted\<kcroot>
    copy %vanguard_setup%\kc\kc_welcome_template C:\KCHosted\<kcroot>
    copy %vanguard_setup%\kc\server.xml C:\WASLiberty\wlp\usr\servers\kc
    copy %vanguard_setup%\kc\server.env C:\WASLiberty\wlp\usr\servers\kc
    
  5. Add the following location to the C:\Apps\Apache2\conf\httpd.conf file:

    # Proxy path for kc so that port number isn't required
    <Location "/kc">
      ProxyPass http://localhost:9090/kc
      ProxyPassReverse http://localhost:9090/kc
      ProxyPassReverseCookiePath
      http://localhost:9090/kc /kc
    </Location>
    
  6. Create a Windows scheduled task to start KC when the computer boots. Create the task as an Administrator user:

    • On the General tab, specify that it Run whether user is logged on or not and run as the Administrator user.
    • On the Triggers tab, add a trigger to begin At startup
    • On the Action tab, specify:
      • Action: Start a program
      • Program/script: server
      • Add arguments: start kc
      • Start in: C:\WASLiberty\wlp\bin
  7. Run the perl script that creates Jenkins job queues to create KCJob queues on this computer if you haven’t already.

On each server that will process returned NL packages

  1. Create a file named C:\openldap\sysconf\ldap.conf with the following contents:

    TLS_REQCERT never
    TLS_CACERT C:\Apps\Apache2\conf\bluepages.cert
    

    (The OpenLDAP implementation in PHP 5.3.x uses this static location for the OpenLDAP configuration settings. OpenLDAP is used by the Vanguard SOAP Server to authenticate the credentials in the header.)

  2. Edit the httpd.conf file, add the following to the <IfModule alias_module> section, and restart Apache.

    Alias /DVT  "C:/p/vgnlv/web"
    <Directory "C:/p/vgnlv/web">
        Options Indexes FollowSymLinks
        AllowOverride All
        Order allow,deny
        Satisfy Any
        Allow from all
    </Directory>
    
    Alias /proc  "C:/p/vgnlv/proc"
    <Directory "C:/p/vgnlv/proc">
        Options Indexes FollowSymLinks
        AllowOverride All
        Order allow,deny
        Satisfy Any
        Allow from all
    </Directory>