Polytomic On-Premises

Most of the information on hosting Polytomic on-premises can be found alongside the rest of our documentation. If you are new to Polytomic on-premises, that is the best place to start. This repo contains instructions for setting up Polytomic on specific container deployment platforms.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Deployments
   • ECS
   • Docker Compose
   • Aptible
   • GKE
   • EKS
   • KIND
   • Helm
3. Contributing

About The Project

Before beginning, please read the On-Premises Setup document.

During setup you will need a specific tagged version to deploy. You can find version tags and their changelogs here: https://docs.polytomic.com/changelog

(back to top)

Deployments

Polytomic offers a number of deployment options. The following sections will walk you through the steps to deploy Polytomic on each platform.

ECS

Follow the steps in the ECS terraform module to deploy Polytomic on ECS.

A number of examples can be found in the terraform/examples directory.

(back to top)

Docker Compose

1. Install Docker on your machine, as well as the AWS cli with your credentials that you'll use to pull the image.
2. Copy the contents of examples/docker-compose.yml into a new file on your host machine.
3. Edit docker-compose.yml:
   • in the api service entry, change the latest docker image tag to a specific release (i.e. rel2021.11.04)
   • Fill in the rest of the mandataory environment variables
   • You can use the built-in docker postgres and redis, but it is highly recommended you configure these as separate redis/postgres instances.
     • To do so, just delete the top-level postgres and cache service blocks in docker-compose.yml and specify your connection strings in the environment variables.
4. run docker compose up -- traffic should be served on localhost:5100

To upgrade:

1. docker compose down
2. Edit docker-compose.yml to change the release version of the image. Please use a concrete version tag rather than latest.
3. docker compose up

(back to top)

Aptible

1. Add your public SSH key to your Aptible account through the Aptible dashboard

2. Install the Aptible CLI (instructions).

3. Login to Aptible CLI if you haven't already: aptible login.

4. Clone this repo: git clone https://github.com/polytomic/polytomic-onprem

5. Change the working directory to the newly cloned repository: cd polytomic-onprem

6. Specify the version of Polytomic that you'd like to install in the Dockerfile, and commit it. You can see a full release catalog in the Changelog. We strongly suggest specifying a version number when deploying. For example: 568237466542.dkr.ecr.us-west-2.amazonaws.com/polytomic-onprem:rel2021.06.08.02

7. Create a new Aptible app: aptible apps:create your-app-name

8. The result of apps:create will be a git remote url. It's a good idea to setup your remote right now: git remote add <aptible-git-remote-url>

9. If you are not bringing your own database, create one: aptible db:create your-database-name --type postgresql. Record the value of the newly created database credentials. If you are providing your own database, please make sure to grant the Polytomic user superuser rights to its own database.

10. If you are not bringing your own cache, create one: aptible db:create <db-name> --type redis --version 5.0. Record the value of the newly created database credentials.

11. Polytomic uses Google SSO in order to handle authentication. You will need to setup an OAuth client for Polytomic.

    • In your OAuth Client configuration, Google will allow you to specify Authorized Javascript Origins. Set this to https://$POLYTOMIC_HOST.
    • In your OAuth Client configuration, Google will allow you to specify Authorized Redirect URIs. Set this to https://$POLYTOMIC_HOST/auth.

12. Use the above database values, along with Polytomic-provided values in order configure the app. Note: Polytomic needs to know the URI you are hosting it on. If you intend to use an aptible-supplied hostname, you can remove it from here and setup it up later.

    aptible config:set --app your-app-name \
        ROOT_USER=<first@users.email> \
        DEPLOYMENT=<identifier-provided-by-polytomic> \
        DEPLOYMENT_KEY=<key-provided-by-polytomic> \
        DATABASE_URL=postgresql://<postgres-connection-string> \
        REDIS_URL=redis://<redis-connection-string> \
        POLYTOMIC_URL=https://<uri-you-intend-to-host-polytomic-on> \
        GOOGLE_CLIENT_ID=<google-client-id> \
        GOOGLE_CLIENT_SECRET=<google-client-secret>
    

13. We use the recommended method for synchronized deploys. To do this we:

    1. Get a new AWS ECR auth token: aws ecr get-login-password
    2. Push the code to new branch on aptible without trigging a deploy: git push aptible master:release-2021-06-23
    3. Trigger a deploy using the credentials:

    aptible deploy \
         --app your-app-name \
         --git-commitish release-2021-06-23 \
         --private-registry-username AWS \
         --private-registry-password token-from-aws-ecr-get-login-password
    

14. Navigate to your Aptible control panel and create a new endpoint for Polytomic.

    • You can use a custom CNAME or one generated by Aptible, just be sure to update the app configuration after (using config:set as above)
    • You do not need to change the port (5100 is the default and correct port to expose).

15. You should be able to sign into Polytomic at the specified host with the specified ROOT_USER.

(back to top)

GKE

Follow the steps in the GKE terraform module to deploy Polytomic on GKE.

(back to top)

EKS

Follow the steps in the EKS terraform module to deploy Polytomic on EKS.

(back to top)

KIND (Kubernetes in Docker)

To get a sandbox kubernetes environment set up, run the sandbox script located at hack/sandbox.sh

It will setup a local kind cluster. Then, install the helm chart.

./hack/sandbox.sh

(back to top)

Helm

Add the polytomic chart repo

helm repo add polytomic https://charts.polytomic.com
helm repo update

Download and edit a values.yaml file if desired.

curl https://raw.githubusercontent.com/polytomic/on-premises/master/helm/charts/polytomic/values.yaml -o values.yaml

Install the chart (detailed information about the chart can be found here)

helm install polytomic polytomic/polytomic -f values.yaml

(back to top)

Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Install git hooks (git config core.hooksPath hack/hooks)
3. Create your Feature Branch (git checkout -b feature/AmazingFeature)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

(back to top)