<?xml version="1.0" encoding="UTF-8"?> <chapter version="5.0" xml:id="chapter.deploy" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Deploying the Perforce Web API</title> <para> <emphasis>THIS SECTION IS OBSOLETE.</emphasis> This section comes from the baseline P4 Web API, and only covers the deployment of a very small part of the Perforce Web Services. It will be updated, eventually. </para> <simplesect> <title>Deployment Options</title> <para> The Perforce Web API is a modular Sinatra application. It is a Ruby application that can be deployed in a Rack-compatible web server. We recommend and test using <ulink href="http://puma.io">Puma</ulink>. </para> <para> Setting up a simple puma server is very straightforward. First you will need the puma and p4_web_api gems: </para> <programlisting language="shell"> gem install puma p4_web_api</programlisting> <para> Next, you will launch the p4_web_api app indicating puma as the web server: </para> <programlisting language="shell"> p4_web_api -s Puma</programlisting> <para> Otherwise, you are free to experiment using other framework operations and web server configurations. Please observe the minimum requirements. </para> <para> For example, our recommended Puma setup includes <literal>init.d</literal> and <literal>upstart</literal> scripts for restarting web applications on Linux machines. See the <ulink url="https://github.com/puma/puma/tree/master/tools/jungle/">tools/jungle</ulink> directory of the source distribution. </para> <para> This involves setting up a simple application directory, with a <literal>config.ru</literal> file (described in the configuration section), a <literal>config/puma.rb</literal> file described by the Puma distribution, and a <literal>Gemfile</literal> that indicates the dependencies of the P4 Web API and Puma: </para> <programlisting language="ruby"> source "https://rubygems.org" gem 'p4_web_api', '~> 2014.2.0.pre4' gem 'puma', '~> 2.10.2' </programlisting> <para> Once the files are setup, it's just a matter of running <literal>bundle install</literal> in your application directory, then, launch puma. If you were running upstart on Ubuntu, this would be: <literal>sudo start puma app=/my/app/dir</literal>. </para> <para> Deployment behind nginx, Apache, or IIS is probably a good idea, however, you will have to review how to setup these servers as reverse proxies. </para> </simplesect> <simplesect> <title>System Requirements</title> <itemizedlist> <listitem>Minimum Ruby version: 2.1 or greater of the MRI distribution (standard C Ruby implementation)</listitem> <listitem>Operating systems: Linux or OS X, you will likely have to install Ruby directly via rvm or rbenv; your Ruby version is likely out of date</listitem> </itemizedlist> </simplesect> <simplesect> <title>Configuration</title> <para> Being a Sinatra application, you can instantiate an instance of <literal>P4WebAPI::App</literal> and manipulate the <literal>settings</literal> field of the object to configure the application. Here's an example of a rackup <literal>config.ru</literal> that changes a couple of settings. </para> <programlisting language="ruby"> require 'p4_web_api' p4_web_api = P4WebAPI::App.new p4_web_api.settings.p4 = { 'port' => 'perforce:1666' } p4_web_api.settings.token_path = '/home/perforce/p4_web_api/tokens' run p4_web_api</programlisting> <para> The P4 Web API can also be configured with a single Yaml file, pointed to via the <literal>P4_WEB_API_CONFIG</literal> environment variable. </para> <para> For example, you can create the file <literal>/etc/p4_web_api.yml</literal> and indicate it directly via: </para> <programlisting language="shell"> P4_WEB_API_CONFIG=/etc/p4_web_api.yml p4_web_api -s Puma</programlisting> <para> Here's an example configuration, with details following in a table: </para> <programlisting language="yaml"> p4: port: '1666' host: perforce.example.com token_path: /var/data/p4_web_api/tokens</programlisting> <informaltable> <tgroup cols="4"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry><literal>p4</literal></entry> <entry>Perforce server connection information, should be a group setting with possible string subvalues of <literal>port</literal>, <literal>host</literal>, and <literal>charset</literal>.</entry> <entry>Group</entry> <entry>No</entry> </row> <row> <entry><literal>token_path</literal></entry> <entry>Local filesystem path where we store session tokens with Perforce authentication information. It is strongly recommended that this directory be only readable and writable by the system user used to launch the web server process. Defaults to <literal>/tmp/p4_web_api/tokens</literal>, please set this value.</entry> <entry>String</entry> <entry>No, but recommended</entry> </row> <row> <entry><literal>normalize_output</literal></entry> <entry>Defaults to <literal>true</literal>. When <literal>true</literal>, the output of the different commands will be altered to have consistent case naming and use epoch integers for all dates. When <literal>false</literal>, the output will not be as documented in this application, and will closely resemble the output of the <literal>p4</literal> console command with the <literal>-ztag</literal> option enabled.</entry> </row> <row> <entry><literal>allow_env_p4_config</literal></entry> <entry>When <literal>true</literal>, the Perforce server configuration can actually be set via the Rack environment, potentially to allow a single P4 Web API instance to connect to multiple backend servers. Use the variables <literal>P4_PORT</literal>, <literal>P4_HOST</literal>, and <literal>P4_CHARSET</literal> to allow the request to hit a different Perforce instance. Defaults to <literal>false</literal>.</entry> <entry>String</entry> <entry>No</entry> </row> </tbody> </tgroup> </informaltable> </simplesect> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#3 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#2 | 13553 | tjuricek | Update deployment instructions for the current state. | ||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |
||
//guest/perforce_software/helix-web-services/main/p4_web_api/p4_web_api/docbook/xml/02_deploy.xml | |||||
#1 | 13412 | tjuricek |
Initial version of the web-services mainline. This is a collection of several projects, that will likely often get released together, though many of them may not always be relevant. See the README for more information. |