# Getting Started

This document describes the implementation of the Server version of On-Prem. See the [On-Prem Overview](http://developer.factual.com/geopulse-on-prem-overview/) for a higher-level introduction to On-Prem. Before provisioning servers, see the [Hardware Guidance](http://developer.factual.com/geopulse-on-prem-overview#hardware) 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:

Shell

```shell
$ createuser factual
```

## Download On-Prem Server

Next, download the latest On-Prem Server binary [here](https://s3.amazonaws.com/artifacts.geopulse.factual/geopulse-server/geopulse-server-3.3.0.tar.gz). Unpack and copy the provided files to `/usr/local/factual/outpost`.

Shell

```shell
$ 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:

Shell

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

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

Shell

```shell
$ 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.

YAML

```yaml
# 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.

YAML

```yaml
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](http://upstart.ubuntu.com/). 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:

Shell

```shell
$ limit nofile 500000 500000
```

# Running the Server

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

Shell

```shell
$ sudo start outpost
```

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

Shell

```shell
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.

Shell

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

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

Shell

```shell
$ sudo stop outpost
$ sudo restart outpost
```

# Testing Responses

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

Audience test:

Shell

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

Proximity test:

Shell

```shell
$ 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](http://developer.factual.com/geopulse-terminology/) for detailed descriptions of each return value.

**Proximity Response Example:**

JSON

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

**Audience Response Example:**

JSON

```json
[
  {
    "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"
  }
]
```