On-premises setup

Polytomic's Enterprise plan offers an on-premise deployment in the form of a Docker container that runs in your private cloud, wholly self-contained. Contact us through our website to learn more: https://www.polytomic.com/contact.

Environment Requirements

  • Ability to run Docker containers
  • Ability to expose running Polytomic container to external traffic with SSL/TLS termination
  • Databases, as indicated in the next section.
  • A Google OAuth Client, for authentication.

Before You Get Started

In order to deploy Polytomic, you should sort out a few things to make the deploy proceed as smoothly as possible.

  • Get access to the Polytomic ECR on AWS.
  • Receive your Deployment Key from Polytomic.
  • Prepare a PostgreSQL database of at least version 11. The user should have superuser rights to the database. If you are using a deployment platform (e.g. Heroku, Aptible, etc), you may choose to set those up in the course of deployment.
  • Prepare a Redis deployment. If you are using a deployment platform (e.g. Heroku, Aptible, etc), you may choose to set those up in the course of deployment.
  • Setup a Google OAuth client (necessary for the Polytomic app to provide sign-in).

Deploying

Deployment Platforms

Please see our on-prem repo on GitHub. Specific instructions for each deployment platform are maintained there.

Self-hosted Deployments

We ship Polytomic On Premises as a Docker image. To pull the latest version of the software, use the following image name:

568237466542.dkr.ecr.us-west-2.amazonaws.com/polytomic-onprem:latest

A sample Docker Compose configuration is available here.

Configuration

Polytomic accepts configuration via environment variables. The following are required:

  • ROOT_USER The email address to use when starting for the first time; this user will be able to add additional users and configure Polytomic.

  • DEPLOYMENT A unique identifier for your on premises deploy, provided by Polytomic.

  • DEPLOYMENT_KEY The license key for your deployment, provided by Polytomic.

  • DATABASE_URL Connection URL for Polytomic’s database; should be in the form of postgres://user:[email protected]:port/database.

  • REDIS_URL Connection URL for Redis; should be in the form of redis://:[email protected]:6379/.

    For SSL/TLS connections specify the protocol as: rediss (two s’s).

    Note: this was previously named CACHE_URL; Polytomic will still use that environment variable if REDIS_URL is unset, however it is deprecated and will be removed in a future version.

  • POLYTOMIC_URL Base URL for accessing Polytomic; for example, https://polytomic.mycompany.com. This will be used when redirecting back from Google and other integrations after authenticating with OAuth.

  • GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET Google OAuth Client ID and secret, obtained by creating a OAuth 2.0 Client ID

    Your valid redirect URLs must include {POLYTOMIC_URL}/auth.

The following environment variables may also be specified:

  • LOG_LEVEL Controls the logging output; valid values are debug, info, warn, error; the default is info if not specified.

  • LONGSYNC_THRESHOLD Controls how many minutes a sync may run for before an email is sent. Email recipients are those on the Sync Error notification list. Default is 0 (disabled).

  • VALID_ORIGINS A comma delimited list of valid HTTP origins; POLYTOMIC_URL is automatically added to this list.

  • EXECUTION_LOG_BUCKET An AWS S3 bucket name. For example, polytomic-execution-logs. The bucket stores log files containing the records involved in a sync execution. Record logging is enabled from the Settings page within the app. Credentials for AWS are pulled through the AWS-SDK's credential chain, and the user/role must have permissions for the bucket. We recommended setting a bucket lifecycle rule to automatically expire objects.

  • EXECUTION_LOG_REGION The AWS S3 region for the execution log bucket. For example us-west-2.

  • EXPORT_QUERY_BUCKET An AWS S3 bucket name. For example, polytomic-export-query. The bucket is used to store query exports run using Polytomic's SQL Runner. Credentials for AWS are pulled through the AWS-SDK's credential chain, and the user/role must have permissions for the bucket. We recommended setting a bucket lifecycle rule to automatically expire objects.

  • EXPORT_QUERY_REGION The AWS S3 region for the export query bucket. For example us-west-2.

Monitoring

The Polytomic On Premises image exposes a health-check endpoint at /status.txt which can be used to verify the container is up and running.

First Run

Database Schema

Polytomic runs database migrations on startup. Therefore the database user accessing the Polytomic database will need permission to create and alter the schema.

Organization and User

Polytomic uses GSuite for authenticating users. The first user email address is set via the ROOT_USER environment variable. This user will be able to add additional users through the web interface.

Note that you only need to add users who will be setting up connections and syncs to Polytomic.

Data We Record

Polytomic On Premises makes the following outbound requests:

  • Periodic requests to ping.polytomic.com to verify your license is valid and to record usage telemetry; telemetry does not include any personally identifiable information.
  • Application traces are sent to DataDog; these may include queries executed, but do not contain variables used while processing the pipeline. These traces help us understand how Polytomic is performing.
  • Errors are sent to Sentry.io when they occur to assist us with debugging; error payloads do not contain values used to trigger the sync.

Integrations and Connections

Some integrations require additional configuration when running on premises. See the integrations documentation for more information.