03_configuration.asc #7

[[system_configuration]]
== Configuration

[[deployment_configuration]]
=== Deployment Configuration

There are a few main tasks to perform after just running the installer to get your system fully operational.
The script `/opt/perforce/helix-web-services/bin/hws_configure` can be run on most "clean" operating systems to perform all of these steps.
Not all of these steps will be performed, necessarily.
For example, if you already have nginx running, we will not modify your system configuration.
You will have to configure a reverse proxy to the unicorn server running at port 9000.

[cols="2*", options="header"]
|===
| Description
| Default set by `hws_configure`
| Notes

| Establish the user account for running Helix Web Services
| helixwebservices
| Will not be created if already exists

| Create directory for temporary data, assign to user account
| `/var/lib/perforce/helix_web_services`
| Will not be created if already exists

| Create directory for logging data, assign to user account
| `/var/log/perforce/helix_web_services`
| Will not be created if already exists

| Link upstart configuration
| `/etc/init/helix_web_services.conf` is linked from `/opt/perforce/helix-web-services/etc/init/helix_web_services.conf`
|

| Install and configure nginx
| nginx is installed from system packages, a self-signed key is created or installed, and the default /etc/nginx/nginx.conf is setup as a reverse proxy to Unicorn running at port 9000
| If nginx is already installed, *none of these steps* will be performed.

| Install and configure a Helix Versioning Engine for evaluation
| Installs the `perforce-server` system package, and then configures a `helix-evaluation` instance to run at port 1666.
| If `perforce-server` is already installed, does nothing.
|===

For details of the steps taken, review the script code online at:

https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services/files/main/source/helix_web_services/bin/hws_configure


=== Available Application Settings

System default settings for Helix Web Services can be set by creating a YAML file at `/etc/perforce/helix_web_services.conf`.
If you're unfamiliar with YAML, you simply use the variables below in simple key-value pairs.
Pay attention, however, to the type of the variable.
In many cases we use strings when you might have thought it were a number.

For example:

/etc/perforce/helix_web_services.conf
----
P4PORT: 'perforce.mycompany.com:1999'
----

Many settings in Helix Web Services are overridable by HTTP headers on a per-request basis.
The "Overridable" column in the table below means you can specify this header.
If it is not available, you can _only_ specify the configuration in the system config file.
For more information on specifying the system header, see <<per_request_configuration>>.

[cols="5*", options="header"]
|===
| Variable
| Type
| Overridable
| Description
| Default

| `COMMAND_WHITELIST`
| Array
| No
| Allows access to run commands via <<get_p4_vX_commands_command>> or <<post_p4_vX_commands_command>>.
  Each element in the array is either the name of a command to allow, or an array of the command name and any required arguments.
| `["info", ["files", "-m"]]`

| `CUSTOM_SCRIPTS`
| String
| No
| The local directory that will load up user defined Ruby scripts.
| /var/lib/perforce/helix_web_services/scripts

| `ENABLE_GIT_FUSION`
| Boolean
| No
| Switch to enable GitFusion endpoints.
| false

| `CLOUD_SETTINGS`
| String
| No
| Settings file to load to enable running against Helix Cloud
| config/hws_settings.conf

| `HVE_PROJECTS_PATH`
| String
| Yes
| The depot location in the Helix Versioning Engine that hosts all projects in that server.
|

| `P4HOST`
| String
| Yes
| The hostname for the perforce server, e.g., `perforce.example.com`
|

| `P4PORT`
| String
| Yes
| The port number (or port and hostname combination) that indicates our Perforce connection
| `1666`

| `P4CHARSET`
| String
| Yes
| The charset value for P4 connections.
  Set to `none` if you are connecting to a non-unicode server.
| `auto`

| `P4PASSWD`
| String
| Yes
| The user password to use for p4 connections.
  For many cases, like where the authentication source is a p4d server, this
  will default to the authentication token password.
|

| `SERVICE_CONFIGURATION`
| String
| No
| Local file location that defines how services are to be configured.
| `/etc/perforce/services.json`

| `TRUST_FINGERPRINTS`
| String
| No
| Local file path that indicates a list of allowed SSL fingerprints.
|

| `WORKSPACE_DIR`
| String
| No
| The local directory used for generating temporary Perforce Client Workspaces to do some basic operations.
| `/var/lib/perforce/helix_web_services/workspaces`

|===