Getting Started

This document describes the implementation of the Server version of On-Prem. See the On-Prem Overview for a higher-level introduction to On-Prem. Before provisioning servers, see the Hardware Guidance in the On-Prem Overview.

Required Software

The On-Prem HTTP Server is developed and tested against the following system environment:

Oracle JDK 7
Ubuntu 14.04

The following packages are also required:

upstart (installed by default on Ubuntu)
cronolog

Use only the Oracle JDK — issues with the SSL implementation of OpenJDK have been encountered in production deployments which can prevent On-Prem from updating its audience and geofence data.

Installation

Create a new user

First create a new user:

$ createuser factual

Download On-Prem Server

Next, download the latest On-Prem Server binary here. Unpack and copy the provided files to /usr/local/factual/outpost.

$ mkdir -p /usr/local/factual/outpost
$ cd /usr/local/factual/outpost
$ wget [download link]
$ tar -xvzf outpost-3.1.4-example.tar.gz
$ cp -a outpost-3.1.4-example/. /usr/local/factual/outpost/

You’ll also want to create the following directory for storing logs:

$ mkdir -p /var/log/factual/outpost

Copy the outpost.conf file provided in the top-level into /etc/init.

$ cp /usr/local/factual/outpost/outpost.conf /etc/init/outpost.conf

Edit your config file

Edit the config.yml file, and add in your Organization ID under the comment “the organization-id for the user”. Your account manager can provide this value upon request.

# the organization-id for the user
b3bda92e-b4b5-4012-bccc-48017cdefc81:
  # the credentials for the organization, available via http://factual.com
  api-key: ""
  secret-key: ""

Next configure the values for source that you will pass in to On-Prem. source is the data source/exchange on which the impression originated. Your config.yml file supports aliasing of data sources. This means that you can map the name of the exchange you pass to On-Prem, to the name that Foursquare uses to refer to that exchange.

The following table provides a mapping of these values:

Data Source/Exchange	Foursquare Source Value
MoPub	mopub
AOL One	nexage
Smaato	smaato
Aerserv	aerserv
OpenX	openx
Factual	factual_dap

Per the snippet below, setup your config.yml with your desired data source mappings.

global:
  directory: /tmp/on-prem/test-org
test:
  audience:
    sets:
      max-memory: 1
      fields: [designId, targetingCode, dataSource]
      deployment-tags: []
      data-source-aliases:
        aerserv: internalAerservName
        mopub: internalMoPubName
        nexage: internalAOLName
        smaato: internalSmaatoName

Using Upstart

We strongly recommend using Upstart. Under normal operation, On-Prem Server should never crash. However, if it should, you can take the simple precaution of using Upstart to help maintain availability in production.

You’ll need to confirm that your server can open a large number of file descriptors, which can be done with the following command:

$ limit nofile 500000 500000

Running the Server

Startup the On-Prem server by running the following command:

$ sudo start outpost

Once the server is running, the following message should appear in /var/log/factual/outpost/outpost.log:

started HTTP server on 8989

If desired, the port can be changed in the outpost.conf file. You can confirm that the server is running by hitting the /zz/health endpoint.

$ curl http://localhost:8989/zz/health
ok

The server can be stopped and restarted with the following commands:

$ sudo stop outpost
$ sudo restart outpost

Testing Responses

Use curl for testing your installation. Remember to wrap the URL in quotes:

Audience test:

$ curl "http://[server]/geopulse/audience?user-id=<device_id>&source=<data_source>"

Proximity test:

$ curl "http://[server]/geopulse/proximity/indices?latitude=40.642875&longitude=-73.782991"

Match Response

Although Proximity and Audience are two different products, with their own specific use cases, On-Prem powers each, or both concurrently. To facilitate integration and onboarding, we’ve designed the response packets to be identical:

Attribute	JSON Field	Description
Design Name	designName	Name of the Proximity or Audience Design, assigned in the Designer UI.
Design ID	designId	Foursquare-generated unique ID for the Design.
Deployment ID	deploymentId	Foursquare-generated unique ID for the associated deploy of the Design.
Deployment Tags	deploymentTags	String tags associated with the deploy of the Design as assigned.
Targeting Code	targetingCode	A string assigned to the Set when designing the Design in the Designer UI. (In deprecated versions this was formerly called the “Group ID”.)
Data Source	dataSource	Foursquare-provided ID for the associated audience data source. (Audience only)
Metadata	metadata	A map of keys and values describing the matched set within the Design.
Payload	payload	JSON payload describing the matched set, available as string or bytes (Proximity only)

See the page on Terminology for detailed descriptions of each return value.

Proximity Response Example:

[
  {
    "designName": "BigBox",
    "targetingCode": "Costco",
    "deploymentId": "ABCEHGEEG3q45hasdShe",
    "setId": "xyzHGEEG3q45hasdShe"
  }, 
  {
    "designName": "Electronics",
    "targetingCode": "Best Buy",
    "deploymentId": "ABMnOwHGbdcG3q45haoazq",
    "setId": "xyzHGEqa68Dxhasdhe"
  }
]

Audience Response Example:

[
  {
    "designName": "affluent-business-travelers",
    "designId": "17914b5c-899b-434a-b343-cbadec91e7ca",
    "targetingCode": "affluentBiz",
    "deploymentId": "AyoLwbEHGbdcG3q45haoae",
    "setId": "xyzHlQbiqa353q45ha3h9e"
  }, 
  {
    "designName": "san-diego-moms",
    "designId": "9653e9dd-236d-4c53-8398-ca73a3876343",
    "targetingCode":"SanDiegoMoms",
    "deploymentId": "ABCEHGbdcGwZqb3q45hao9e8",
    "setId": "xyzHqGExqsa353q45hys5he7"
  }
]