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

Deploying

We ship Polytomic On Premises as a Docker image, and provide Terraform modules for supported deployment configurations, including ECS, EKS, & GKE. Deployment via Terraform helps ensure your deployment is correctly configured. Please contact us if you are using another orchestration tool.

To pull the latest version of the software, use the following image name:

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

Note: it is recommended that you use a specific release version rather than latest whenever possible.

Configuration

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:password@host:port/database.
REDIS_URL Connection URL for Redis; should be in the form of redis://:password@host:6379/.

For SSL/TLS connections specify the protocol as: rediss (two s’s).
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.
DEFAULT_OPERATIONAL_BUCKET The URL of the bucket to use for storing artifacts (logs, query results, job payloads). For example, s3://acmeinc-polytomic?region=us-west-2. The container must operate with a role that allows Polytomic to write to the specified bucket. We recommend setting a bucket lifecycle rule to automatically expire objects.

The following environment variables may also be specified:

DEPLOYMENT_LINKS Additional deployment-specific links may be added to the Polytomic navigation bar by setting this. The value is a JSON-encoded array of objects. For example:

DEPLOYMENT_LINKS='[{"url":"https://polytomic.com", "name":"Polytomic Homepage"}]'

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

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.

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.

SSO (Single-Sign On)

Polytomic's default on-premise login mechanism is Google SSO. If you'd like to add other SSO options (e.g. Okta), please follow these instructions:

Log in to the shell of your Polytomic host.
Run this command to obtain the OIDC Connect URL to enter into your SSO provider console: ptctl org info.
Enter the OIDC (OpenID Connect) URL in the client configuration in your SSO provider's console.
Go back to the shell of your Polytomic host and run this command: ptctl org update. Enter the following:
1. SSO Domain: the domain of your company (e.g. mycompany.com).
2. Issuer: the URL of your OIDC identity provider, obtained from your SSO provider's console (e.g. https://dev-61270112.okta.com).
3. Client ID: obtained from your SSO provider's console.
4. Client Secret: obtained from your SSO provider's console.
5. (Optional) You can disable logging in through Google by unsetting the environment variables GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your Polytomic environment.

You'll now be able to log in using your SSO provider by clicking on this link in Polytomic: