This document describes the implementation of the Server version of Geopulse On-Prem. See the Geopulse On-Prem Overview for a higher-level introduction to Geopulse On-Prem. Before provisioning servers, see the Hardware Guidance in the Geopulse On-Prem Overview.
The Geopulse On-Prem HTTP Server is developed and tested against the following system environment:
The following packages are also required:
Use only the Oracle JDK — issues with the SSL implementation of OpenJDK have been encountered in production deployments which can prevent Geopulse On-Prem from updating its audience and geofence data.
First create a factual user:
$ createuser factual
Next, download the latest On-Prem Server binary from the On-Prem Downloads page. Unpack and copy the provided files to
$ 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
outpost.conf file provided in the top-level into
$ cp /usr/local/factual/outpost/outpost.conf /etc/init/outpost.conf
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 Factual uses to refer to that exchange.
The following table provides a mapping of these values:
|Data Source/Exchange||Factual Source Value|
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
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
Startup the On-Prem server by running the following command:
$ sudo start outpost
Once the server is running, the following message should appear in
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
$ curl http://localhost:8989/zz/health ok
The server can be stopped and restarted with the following commands:
$ sudo stop outpost $ sudo restart outpost
Use curl for testing your installation. Remember to wrap the URL in quotes:
$ curl "http://[server]/geopulse/audience?user-id=<device_id>&source=<data_source>"
$ curl "http://[server]/geopulse/proximity/indices?latitude=40.642875&longitude=-73.782991"
Although Geopulse Proximity and Geopulse Audience are two different products, with their own specific use cases, Geopulse On-Prem powers each, or both concurrently. To facilitate integration and onboarding, we’ve designed the response packets to be identical:
|Design Name||designName||Name of the Geopulse Proximity or Audience Design, assigned in the Designer UI.|
|Design ID||designId||Factual generated unique ID for the Design.|
|Deployment ID||deploymentId||Factual 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||Factual provided ID for the associated audience data source. (Geopulse 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 Geopulse Terminology for detailed descriptions of each return value.