Skip to main content

Docker Kubernetes Manifest Installation

Retool does not recommend deploying to physical machines for team development and deployments. Consider deploying to managed Kubernetes services such as Amazon EKS, Azure Kubernetes Service, or Google Kubernetes Engine.

The following example focuses on using Kubernetes on Docker Desktop for education purposes.

Requirements​

To deploy Retool using Docker, you need:

  • A Retool license key, which you can obtain from my.retool.com or your Retool account manager.
  • A working installation of Docker desktop.
  • Kubernetes enabled on Docker Desktop.

Self-hosted deployments also require the following and are configured within Docker Desktop Settings/Resources:

  • OS Supported by Docker Desktop
  • 12GiB memory
  • 6 vCPUs
  • 60GiB storage.

Steps​

Run the following command to download the installation.

curl -L -O https://github.com/tryretool/retool-onpremise/archive/master.zip \
&& unzip master.zip \
&& cd retool-onpremise-master
  • Download the Manifests and update (limits, secrets, image tag)
  • Download the manifests by running the following command to get four manifest files:
curl -L -O https://github.com/tryretool/retool-onpremise/archive/master.zip && unzip master.zip
cd retool-onpremise-master/kubernetes

Once the command is run, the directory should have the following contents:

ls -l
total 32
-rw-r--r--  1 criley  staff  2471 Sep 11 11:36 retool-container.yaml
-rw-r--r--  1 criley  staff  1998 Sep 11 11:36 retool-jobs-runner.yaml
-rw-r--r--  1 criley  staff  1429 Sep 11 11:36 retool-postgres.yaml
-rw-r--r--  1 criley  staff   546 Sep 11 11:36 retool-secrets.template.yaml

Secret Updates​

Copy the retool-secrets.template.yaml to retool-secrets.yaml. Edit retool-secrets.yaml to enter in the Retool license key. Opening the yaml document will appear as follows:

apiVersion: v1
kind: Secret
metadata:
  name: retoolsecrets
type: Opaque
data:
  jwt_secret: {{ random base64 encoded string to sign jwt tokens }}
  encryption_key: {{ random base64 encoded string to encrypt database credentials }}
  postgres_password: {{ random base64 encoded string to set as the internal retool db password }}
  license_key: {{ base64 encoded string of the license key Retool will provide you }}
  google_client_id: {{ google client id encoded in base64 }}
  google_client_secret: {{ google client secret encoded in base64 }}

Use the following commands to generate random unique base64 entries for jwt_secret, encryption_key.

openssl rand -base64 16 //take result and put into jwt_secret line
openssl rand -base64 16 //take result and put into encryption_key line

Take the Retool license key and use the following command to generate a base64 encoded string:

echo -n "ENTER RETOOL LICENSE KEY HERE" | openssl base64

Create base64 encoded value for the Postgres DB Password, use the following command:

echo -n "ENTER POSTGRES PASSWORD HERE" | openssl base64

NOTE: The following values are not required for this POC, just place random text here and update the retool-secrets.yaml. These entries are examined on startup by the jobs-runner and api pods as part of their environment settings.

Create base64 encoded value for the Google Client ID, use the following command:

echo -n "Google Client ID HERE" | openssl base64

Create base64 encoded value for the Google Client Secret, use the following command:

echo -n "Google Client Secret HERE" | openssl base64

Image updates​

Edit the retool-jobs-runner.yaml and retool-container.yaml to have an image id specified. For example:

image: tryretool/backend:3.12.4

Limit updates​

It is important that you are aware that the container and jobs-runner manifests have CPU/Memory limits defined and this could cause OOMKilled errors when deploying. Please edit the retool-jobs-runner.yaml to reduce the resources to:

resources:
          limits:
            cpu: "2"
            memory: 2048M
          requests:
            cpu: "1"
            memory: 1024M
  • Deploy the secrets manifest using the following command:
kubectl apply -f retool-secrets.yaml
secret/retoolsecrets created

Check to make the sure the secrets were applied using the following command:

kubectl get secrets
NAME            TYPE     DATA   AGE
retoolsecrets   Opaque   4      32s
  • Deploy the postgres manifest using the following command:
kubectl apply -f retool-postgres.yaml
persistentvolumeclaim/postgres-pvc created
deployment.apps/postgres created
service/postgres configured

Check to make sure the postgres deployment / pod have successfully deployed using the following command:

kubectl get pods
NAME                        READY   STATUS    RESTARTS   AGE
postgres-69898447dd-9zs2v   1/1     Running   0          31s

Also check the logs to make sure that the postgres pod is accepting connections.

kubectl logs <postgres pod name>
2023-11-08 15:19:05.088 UTC [1] LOG:  database system is ready to accept connections
  • Deploy the jobs-runner manifest using the following command:
kubectl apply -f retool-jobs-runner.yaml
deployment.apps/jobs-runner created

Check to make sure the jobs-runner deployment / pod have successfully deployed using the following command:

kubectl get pods
NAME                          READY   STATUS    RESTARTS   AGE
jobs-runner-85b7d4577-9wp55   1/1     Running   0          78s
postgres-69898447dd-9zs2v     1/1     Running   0          104s

Also check the logs to make sure that the jobs-runner pod is executing migrations.

kubectl logs <jobs-runner pod name>
{"level":"info","message":"Jobs runner checking for changes.","pid":41,"source":"JOBS_RUNNER","timestamp":"2023-11-08T15:39:33.931Z"}
  • Deploy the container manifest using the following command:
kubectl apply -f retool-container.yaml
deployment.apps/api created
service/api unchanged
persistentvolumeclaim/retool-pvc created

Check to make sure the api deployment / pod have successfully deployed using the following command:

kubectl get pods
NAME                          READY   STATUS    RESTARTS   AGE
api-79fb8468f-lbzpv           1/1     Running   0          29s
jobs-runner-85b7d4577-9wp55   1/1     Running   0          3m38s
postgres-69898447dd-9zs2v     1/1     Running   0          4m4s

Also check the logs to make sure that the api pod is receiving health checks with a HTTP 200 status code from K8S. It will take several minutes for the K8S health check to display.

kubectl logs <api pod name>

Acquire the api service IPV4 address​

When the container manifest is deployed, it creates a service of type LoadBalancer. Determine the Kubernetes service values for the api service. Use the following command:

kubectl get svc
NAME         TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
api          LoadBalancer   10.106.234.225   localhost     3000:30540/TCP   7d21h
demo         ClusterIP      10.98.186.210    <none>        80/TCP           7d21h
kubernetes   ClusterIP      10.96.0.1        <none>        443/TCP          83d
postgres     ClusterIP      None             <none>        55555/TCP        16d

Confirm that you can access the Retool Login Page by going to:

http://<api svc EXTERNAL-IP>:3000

Cleanup of Retool Installation​

The following steps can be used to cleanup the Retool Platform K8S artifacts.

Delete the Deployments​

kubectl delete deployment api jobs-runner postgres

Delete the Secret​

kubectl delete secret retoolsecrets

Delete the Persistent Volume Claim​

kubectl get pvc
kubectl delete pvc <pvc name>