02_deploy.asc #13

== Deploying Helix Web Services

=== Obtaining HWS

WARNING: We have not yet defined exactly how people will download HWS.
It is likely that we'll have a section under plugins & integrations, or server utilities.
Once this is defined, we'll need to complete this section.

=== Quick Start of HWS

Before you can install Helix Web Services, you will need to ensure Java 8 has been installed and configured on your machine.
If you intend to connect to p4d over TLS, you will need to additionally configure the Java Cryptography Extensions.
For more inforamtion, see the section <<setup_java_8>>.

Depending upon your operating system, you will have a slightly different experience getting started with Helix Web Services.

* <<quick_start_linux_package>>
* <<quick_start_binary_archive_unix>>
* <<quick_start_binary_archive_unix>>
* <<quick_start_binary_archive_windows>>

[[setup_java_8]]
==== Install Java 8 with Java Cryptography Extensions

You should ensure your operating system has Java 8, and it is recommended to include the Java Cryptography Extensions to allow Helix Web Services to connect to a TLS-enabled p4d server.

At a minimum, you should be able to run `java -version` from a terminal and see output like the following:

....
 $ java -version
java version "1.8.0_73"
Java(TM) SE Runtime Environment (build 1.8.0_73-b02)
Java HotSpot(TM) 64-Bit Server VM (build 25.73-b02, mixed mode)
....

If you do not receive Java version 1.8 or greater, follow the instructions for your operating system:

* <<setup_java_8_ubuntu>>
* <<setup_java_8_centos>>
* <<setup_java_8_osx>>
* <<setup_java_8_windows>>

Then, continue on with <<check_for_jce>>

[[check_for_jce]]
===== Checking for Java Cryptography Extensions

Your Java distribution requires the Java Cryptography Extensions in order to connect to p4d via TLS.

A simple way to check for JCE is to create a basic program and run it.
Start by saving this file as `Test.java`:

[source,java]
.Test.java
....
import javax.crypto.Cipher;

class Test {
  public static void main(String[] args) {
    try {
      int maxKeyLen = Cipher.getMaxAllowedKeyLength("AES");
      System.out.println("maxAllowedKeyLength for AES: " + maxKeyLen);
    } catch (Exception e){
      System.out.println("JCE does not appear to be installed");
    }
  }
}
....

Then, from a terminal window, compile and run:

....
 $ javac Test.java
 $ java Test
....

If JCE is installed, you should see a large number:

....
maxAllowedKeyLength for AES: 2147483647
....

Otherwise, you will see the following:
....
JCE does not appear to be installed
....

If you do not have JCE, you should follow instructions appropriate for your operating system:

* <<setup_jce_linux>>
* <<setup_jce_osx>>
* <<setup_jce_windows>>

[[setup_java_8_ubuntu]]
===== Install Java 8 on Ubuntu-based systems

First, for Ubuntu 14.10 and later, you should be able to install using `apt-get`:

....
 $ sudo apt-get install openjdk-8-jdk
....

For Ubuntu versions 14.04 and earlier, you will need to add the following PPA before installing:

....
 $ sudo add-apt-repository ppa:openjdk-r/ppa
 $ sudo apt-get update
 $ sudo apt-get install openjdk-8-jdk
....

[[setup_java_8_centos]]
===== Install Java 8 on CentOS-based systems

The package name to install is `java-1.8.0-openjdk-devel`, and can be installed via yum:

....
 $ sudo yum install java-1.8.0-openjdk-devel
....


[[setup_java_8_osx]]
===== Install Java 8 on OS X systems

The Java 8 JDK is provided by Oracle on OS X.
It's recommended to use their package installer.

Basic steps:

1. Go to the Java SE Development Kit download page: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
2. Accept the license agreement.
3. Download the file for 'Mac OS X', typically named something like `jdk-8u91-macosx-x64.dmg`.
4. Once downloaded, open the .dmg file, and double click the .pkg file to launch the installer.
5. In the dialog, select `Continue`, and then `Install`.
6. Click `Close` to finish the installation.
7. Double check that java is installed by checking the output of `/usr/libexec/java_home`. It should point to a directory like `/Library/Java/JavaVirtualMachines/jdk1.8.0_91.jdk/Contents/Home`.

[[setup_java_8_windows]]
===== Install Java 8 on Windows systems

The Java 8 JDK is provided by Oracle on Windows.
It's recommended to use their package installer.

Basic steps:

1. Go to the Java SE Development Kit download page: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
2. Accept the license agreement.
3. Download the file for 'Windows x64', typically named something like `jdk-8u92-windows-x64.exe`.
4. Once downloaded, double click the .exe file to launch the installer.
5. Install Java, and note the default location, typically `C:\Program Files\Java\jdk1.8.0_91`.
+
NOTE: Oracle is notorious for changing the installation process on Windows from one update to another.
Take care not to have any unwanted toolbar helpers or other bloatware they may have added to the process.
+
6. Double check that java is installed by opening up a Command Prompt window, and typing `java -version` into it.
+
If java is not recognized, it is likely that you need to add the path `C:\ProgramData\Oracle\Java\javapath` to your system's PATH environment variable.


[[setup_jce_linux]]
===== Setup JCE on Linux systems

Installing the Java Cryptography Extensions involves copying over two .jar files into your JRE distribution's `lib/security` directory.

1. Navigate to the JCE download page at http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
2. Accept the binary code license agreement.
3. Download `jce_policy_8.zip`
4. Extract `jce_policy_8.zip`, typically via unzip:
+
....
 $ unzip jce_policy_8.zip
....
+
This should have created a directory `UnlimitedJCEPolicyJDK8` in your local directory.
5. Typically, the directory you will copy files to is determined by `$(dirname $(dirname $(readlink -f $(which javac))))/jre/lib/security`.
+
Execute `ls` and verify that `local_policy.jar` and `US_export_policy.jar` files are available:
+
....
 $ ls $(dirname $(dirname $(readlink -f $(which javac))))/jre/lib/security
blacklisted.certs  cacerts  java.policy  java.security  local_policy.jar  nss.cfg  US_export_policy.jar
....
+
6. Overwrite the policy JAR files, `local_policy.jar` and `US_export_policy.jar`:
+
....
 $ cp UnlimitedJCEPolicyJDK8/local_policy.jar $(dirname $(dirname $(readlink -f $(which javac))))/jre/lib/security
 $ cp UnlimitedJCEPolicyJDK8/US_export_policy.jar $(dirname $(dirname $(readlink -f $(which javac))))/jre/lib/security
....
+
7. At this point you should be able to retest that your distribution has JCE extensions installed properly (see <<check_for_jce>>).

[[setup_jce_osx]]
===== Setup JCE on OS X systems

Installing the Java Cryptography Extensions involves copying over two .jar files into your JRE distribution's `lib/security` directory.

1. Navigate to the JCE download page at http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
2. Accept the binary code license agreement.
3. Download `jce_policy_8.zip`
4. Extract `jce_policy_8.zip`, typically via unzip:
+
....
 $ unzip jce_policy_8.zip
....
+
This should have created a directory `UnlimitedJCEPolicyJDK8` in your local directory.
5. Typically, the directory you will copy files to is determined by `$(/usr/libexec/java_home)/jre/lib/security`.
+
Execute `ls` and verify that `local_policy.jar` and `US_export_policy.jar` files are available:
+
....
 $ ls $(/usr/libexec/java_home)/jre/lib/security
blacklisted.certs  cacerts  java.policy  java.security  local_policy.jar  nss.cfg  US_export_policy.jar
....
+
6. Overwrite the policy JAR files, `local_policy.jar` and `US_export_policy.jar`:
+
....
 $ cp UnlimitedJCEPolicyJDK8/local_policy.jar $(/usr/libexec/java_home)/jre/lib/security
 $ cp UnlimitedJCEPolicyJDK8/US_export_policy.jar $(/usr/libexec/java_home)/jre/lib/security
....
+
7. At this point you should be able to retest that your distribution has JCE extensions installed properly (see <<check_for_jce>>).

[[setup_jce_windows]]
===== Setup JCE on Windows systems

1. Navigate to the JCE download page at http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
2. Accept the binary code license agreement.
3. Download `jce_policy_8.zip`
4. Extract the `jce_policy_8.zip` using Explorer.
Identify where the `UnlimitedJCEPolicyJDK8` directory is.
5. Open up a new explorer window, and navigate to the `jre\lib\security` folder in your JDK.
+
INFO: This is frequently a path like `C:\Program Files\Java\jdk1.8.0_91\jre\lib\security`.
+
You should see `local_policy.jar` and `US_export_policy.jar`.
6. Copy the `local_policy.jar` and `US_export_policy.jar` files from `UnlimitedJCEPolicyJDK8` folder to the `jre\lib\security` directory.
7. At this point you should be able to retest that your distribution has JCE extensions installed properly (see <<check_for_jce>>).


[[quick_start_linux_package]]
==== Quick Start installing via Linux Packages

WARNING: We do not currently host the linux packages via a package manager.

. <<setup_java_8>>
. Follow the instructions on https://www.perforce.com/perforce-packages to configure your APT or YUM repository manager.
. Install the `helix-web-services` package
.. On APT-based distributions, this is `sudo apt-get install helix-web-services`
.. On YUM-based distributions, this is `sudo yum install helix-web-services`
. Execute the configuration script: `sudo /opt/perforce/helix-web-services/sbin/configure-helix-web-services`
. Optionally, edit the configuration file `./etc/helix-web-services.conf` with any customizations you want.
+
TIP: You probably want to set the `P4PORT`, `HWS_AUTH_P4D` and `P4CHARSET` variables, see <<system_configuration>>.
+
. Setup your p4d connection.
. <<create_p4d_settings>>
. Restart the server
.. On Linux, this is typically `sudo service helix-ws start`
.. On OS X, you'll probably need to run `sudo launchctl load -w /Library/LaunchDaemons/com.perforce.hws.server.HelixWebServices.plist`

[[quick_start_binary_archive_unix]]
==== Quick Start of HWS on Linux or OS X using the Binary Tarball Distribution

Provided you have the binary tarball distribution, `helix-web-services-bin.tar.gz`, you can set it up on your system quickly using the following steps:

. <<setup_java_8>>
. Expand the tarball, typically in a place like `/opt/perforce`:
+
....
 $ sudo mkdir -p /opt/perforce
 $ cd /opt/perforce
 $ sudo tar xzf /path/to/helix-web-services-bin.tgz
....
+
. Run our configuration script:
+
....
 $ sudo ./sbin/configure-helix-web-services
....
. Optionally, edit the configuration file `./etc/helix-web-services.conf` with any customizations you want.
+
TIP: You probably want to set the `P4PORT`, `HWS_AUTH_P4D` and `P4CHARSET` variables, see <<system_configuration>>.
+
. Setup your p4d connection.
. <<create_p4d_settings>>
. Restart the server
.. On Linux, this is typically `sudo service helix-ws start`
.. On OS X, you'll probably need to run `sudo launchctl load -w /Library/LaunchDaemons/com.perforce.hws.server.WebApp.plist`


[[quick_start_binary_archive_windows]]
==== Quick Start of HWS on Windows using the Zipfile Distribution

Provided you have obtained a copy of `helix-web-services.zip`, here's how you can start up an instance quickly:

. <<setup_java_8>>
. Extract the archives of the .zip to a directory, e.g., `C:\helix-web-services`
. Open a Command Prompt as Administrator
. In this command prompt, run the configuration script:
+
....
 cd C:\helix-web-services
 sbin\configure-helix-web-services.exe
....
+
. Optionally, edit the configuration file `C:\helix-web-services\etc\helix-web-services.conf` with any customizations you want.
+
TIP: You probably want to set the `P4PORT`, `HWS_AUTH_P4D` and `P4CHARSET` variables, see <<system_configuration>>.
+
. <<create_p4d_settings>>
. Open your service control manager, and restart `Helix Web Services`.


[[create_p4d_settings]]
==== Create a p4d settings file

Each HWS instance can interact with multiple p4d servers, though, you will need to create an individual <<p4d_settings>> file for each p4d instance.
This will associate an ID with each server, that will be used by your applications to specify which p4d you talk to for most method calls.

The file should be named with the ID you will be used, and placed in the `etc/p4d` directory of your installation.

For example, we'll create an ID called `perforce` and associate it with a Unicode-enabled p4d running on the same machine as HWS:

[source,yaml]
.perforce
....
id: perforce
name: Company Perforce Service
description: A server running on the same instance as HWS
P4PORT: 127.0.0.1:1666
P4CHARSET: utf8
....

In typical a Unix installation this would be saved at the path `/opt/perforce/helix-web-services/etc/p4d/perforce`.



=== Uninstalling Helix Web Services

To completely uninstall Helix Web Services from your system, a simple console script has been provided.

On Unix machines this is typically called with the command:

....
 $ sudo /opt/perforce/helix-web-services/sbin/uninstall-helix-web-services
....

(Substitute the directory `/opt/perforce/helix-web-services` for your installation directory if different.)

On Windows, you will run the `sbin/uninstall-helix-web-services.exe` application with Administrator privileges.

This will completely remove the installation directory from your system.
If you have configuration you wish to retain, please make a copy of that configuration outside of the installation location.