02_deploy.asc #2

== Deploying Helix Web Services

Helix Web Services can be deployed from a source tarball distribution or from installed packages.
Starting up web services from a source tarball is similar to working with code checked out from our source distribution.

To be clear, Helix Web Services will be set up to run a single application server instance.
This application server will run on an unprivileged port, like 9000.
It's expected that Helix Web Services would be a part of a greater ecosystem of web applications, likely proxied by a web server such as Nginx.
Our package installation includes a post-install configuration script that configures other services on the local machine to make it easy.


=== Deploying from a source tarball

The following steps will launch a Helix Web Services instance in the current terminal session.
This is not intended for a production installation, but may be valid for evaluating the product or experimenting with customizing Helix Web Services from source.

Prerequisites to working with our source tarball:

1. Ruby 2.2
2. An installed Perforce server

Other Ruby variations will likely work, we do not test them.

Installation steps:

1. Run: `tar xzf helix-web-services-[VERSION].tar.gz`

2. Run: `cd helix-web-services-[VERSION]/helix_web_services`

3. Run: `bundle install`

4. Run: `bundle exec foreman start`


=== Deploying from Packages

NOTE: Right now you can only obtain unsigned pre-release packages from our workshop website.
See the project page at: https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services/

Install the package using the appropriate platform tool:

 - On Debian or Ubuntu systems, run `dpkg -i helix-web-services-[VERSION].deb`
 - On Redhat or CentOS systems, run `rpm -i helix-web-services-[VERSION].rpm`

After installation, run the configuration script:

----
sudo /opt/perforce/helix-web-services/bin/hws_configure
----

See <<deployment_configuration>> for more details on post-install configuration.

This will have prepared both `helix_web_services` and `nginx` startup scripts.
You should make any adjustments to your system configuration if you need to, and then startup the services.

On Ubuntu, this would take the form:

----
sudo service helix_web_services start
sudo service nginx start
----

If this machine already has an existing nginx or perforce server configuration, you will have to manually configure /etc/nginx/nginx.conf or adjust the system configuration for Helix Web Services.
See <<system_configuration>>.

=== Using `hws_console` to verify your deployment

After installation, you may want to quickly check that your configuration is working as you think it should.
You can use the `hws_console` application to quickly run a few commands in a Ruby console.
A default method, `client_for(user, password)` is available to let you sign in and start running commands.

First, from your login shell, run:

----
/opt/perforce/helix-web-services/bin/hws_console
----

You should be dropped into a Pry session, that will look like the following:

----
From: /opt/perforce/helix-web-services/embedded/lib/ruby/gems/2.2.0/gems/helix_web_services-2015.1.0.pre1/bin/hws_console @ line 18 :

    13:       ssl: {verify: false}
    14:   )
    15: end
    16:
    17: # Drop into the console
 => 18: binding.pry

[1] pry(main)>
----

At the prompt, `[1] pry(main)>`, you can create a client and interact with it.

Say you're using the default configuration, which creates an empty Perforce server with the user `super` with password `superuser1A!`.
You can run the following commands:

----
c = client_for('super', 'superuser1A!')
c.depots
----

While there will be a lot of console debugging output, at the end, you'll see the list of depots in your system.

At this point, `c` is an instance of the `HelixWebServicesClient`.
See link:./helix_web_services_client_ruby/HelixWebServicesClient.html[the Ruby API documentation] for more details on what you can run.

=== Uninstalling Helix Web Services

Completely removing Helix Web Services from the system boils down to a few steps:

* Remove the `helixwebservices` account and group
* Remove the Upstart configuration at `/etc/init/helix_web_services.conf`
* Remove temporary data and logging directories: `/var/lib/perforce/helix_web_services`, `/var/log/perforce/helix_web_services`
* Uninstall or reconfigure nginx
* Uninstall or reconfigure perforce-server
* Run the system package uninstaller, e.g., `apt-get remove helix-web-services`, `dpkg -r helix-web-services`, etc.