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 the supporting infrastructure for Polytomic: setup Redis, Postgres, and Blob storage according to our recommendations. If you are using a deployment platform (e.g. Heroku, Aptible, etc), you may choose to set these up in the course of deployment.
  • Setup a Google OAuth client (necessary for the Polytomic app to provide sign-in).


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:


A sample Docker Compose configuration is available here. Note: it is recommended that you use a specific release version rather than latest whenever possible.


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

  • 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.

  • PORT - the port that the container will expose the HTTP server on

  • EXECUTION_LOG_BUCKET An AWS S3 bucket name. For example: polytomic-execution-logs. The bucket stores log files containing records involved in a sync execution. Record logging is enabled from the Settings page within the app ({POLYTOMIC_URL}/user). Credentials for AWS are pulled through the AWS-SDK's credential chain and the user/role must have permissions for the bucket. We recommend 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 from 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 recommend 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.

  • JOB_PAYLOAD_PATH A blob storage path. For example: s3://polytomic-export-query?region=us-west-2. Other support schemes are file azblob and gcs. The bucket is used to facilitate inter-process communication. Credentials for AWS are pulled through the AWS-SDK's credential chain, and the user/role must have permissions for the bucket. We recommend setting a bucket lifecycle rule to automatically expire objects.

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.

  • GA_MEASUREMENT_ID A value of the format G-XXXXXXX that denotes a Google Analytics instance. Setting this will turn on Google Analytics session tracking for your Polytomic users, with their email addresses used as the Google Analytics user ID.


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.

Workspaces & Users

After Polytomic starts you must create your first workspace via the command line interface.

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.