Setup

Setup Retool in your own VPC.

Retool can be setup on premise in around 15 minutes. You should use either Docker, Kubernetes, or Heroku. If you're not sure what to use, use Docker.

First steps

  1. Spin up a new EC2 instance of Ubuntu 16.04 or 18.04, of at least t2.medium
  2. Open up port 443 and 80 in the network security group, so you can connect to your VPS
  3. Whitelist your VPS's IP address in your database, so you can connect to it
  4. SSH in
  5. git clone https://github.com/tryretool/retool-onpremise.git
  6. cd retool-onpremise
  7. Follow the instructions below for Docker or Kubernetes

A license key is required for on-premise deployments.

You can get a free trial license key by signing into your cloud instance of Retool, going to Settings, then clicking on the Billing tab.

Ubuntu

  1. Install Docker and Docker Compose
./install.sh
  1. Add environment variables to docker.env
# Definitely to do this
LICENSE_KEY=YOUR_LICENSE_KEY 

# This is optional but recommended for a basic trial set-up
COOKIE_INSECURE=true
  1. Start the Retool server
sudo docker-compose up
  1. Confirm that all containers are running
sudo docker-compose ps
  1. Navigate to your server's IP address in a web browser
  2. Click "Sign Up". The first user that signs into an instance becomes the administrator.
  3. Invite your teammates in the Users tab of the Settings page.

CentOS

  1. Install git
sudo yum install git
  1. Clone the Retool repository
git clone https://github.com/tryretool/retool-onpremise.git
  1. Install Docker and Docker Compose
cd retool-onpremise
./install.sh
  1. Make docker-compose available to the root user
sudo ln -s /usr/local/bin/docker-compose  /usr/bin/docker-compose
  1. Enable and start the docker service:
sudo systemctl enable docker.service
sudo systemctl start docker.service
  1. Add environment variables to docker.env
LICENSE_KEY=YOUR_LICENSE_KEY 

# This is optional but recommended for a basic trial set-up
COOKIE_INSECURE=true
  1. Start Retool up!
sudo docker-compose up -d

Ubuntu / CentOS shared

Obtaining a LetsEncrypt SSL Certificate when using Docker

  1. First set up a DNS so that retool.yourcompany.com points to the Retool server
  2. Then edit the docker.env file and change the following line:
# Before
DOMAINS=XX.XXX.XXX.XXX -> http://api:3000

# After
DOMAINS=retool.yourcompany.com -> http://api:3000
  1. Edit the docker-compose.yml file and make the following changes:
# Before
...
  https-portal:
    ...
    environment:
      STAGE: 'local' # <- Change 'local' to 'production' to use a LetsEncrypt signed SSL cert
    networks:
      - frontend-network
...


# After
...
  https-portal:
    ...
    environment:
      STAGE: 'production'
    networks:
      - frontend-network
...

Using a Custom Certificate for SSL

  1. In docker-compose.yml, change image to nginx:latest & add two volumes.

Here's how it should look:

https-portal:
    image: nginx:latest
    ports:
      - '80:80'
      - '443:443'
    links:
      - api
    restart: always
    env_file: ./docker.env
    environment:
      STAGE: 'production' 
    networks:
      - frontend-network
    command: [nginx-debug, '-g', 'daemon off;'] # better error logging in container
    volumes:
      - ./nginx:/etc/nginx/conf.d
      - ./certs:/etc/nginx/certs
  1. Now, create directories for these new volumes. Create /certs directory inside of the retool-onpremise directory and move your certificate and key files into that directory. Create an /nginx directory and create a file called certs.conf in that directory (it can be anything that ends with .conf).
  1. Inside of certs.conf add the following, with your subdomain, certificate, and key filenames substituted.
server {
    listen 80;
    server_name your.subdomain.for.your.company.com;

    location / {
        return 301 https://$host$request_uri;
    }    
}

server {
    listen 443 ssl;
    server_name your.subdomain.for.your.company.com;
    ssl_certificate     /etc/nginx/certs/YOUR_CERT_FILE_NAME.crt;
    ssl_certificate_key /etc/nginx/certs/YOUR_KEY_FILE_NAME.key;

    location / {
        proxy_pass http://api:3000;
    }
}
  1. Run sudo docker-compose up -d

Kubernetes

  1. Navigate into the kubernetes directory
  2. Copy the retool-secrets.template.yaml file to retool-secrets.yaml and inside the {{ ... }} sections, replace with a suitable base64 encoded string.
    1. If you do not wish to add google authentication, replace the templates with an empty string.
    2. You will need a license key in order to proceed.
  3. Run kubectl apply -f ./retool-secrets.yaml
  4. Run kubectl apply -f ./retool-postgres.yaml
  5. Run kubectl apply -f ./retool-container.yaml

For ease of use, this will create a postgres container with a persistent volume for the storage of Retool data. We recommend that you use a managed database service like RDS as a long-term solution. The application will be exposed on a public ip address on port 3000 - we leave it to the user to handle DNS and SSL.

Please note that by default Retool is configured to use Secure Cookies - that means that you will be unable to login unless https has been correctly setup.

To force Retool to send the auth cookies over HTTP, please set the COOKIE_INSECURE environment variable to 'true' in ./retool-container.yaml. Do this by adding the following two lines to the env section.

- name: COOKIE_INSECURE
  value: 'true'

Then, to update the running deployment, run $ kubectl apply -f ./retool-container.yaml

Heroku

Installing

To quickly get going, visit our Github repo and click "Deploy to Heroku"

You'll need at least 1GB of RAM for Retool to start successfully.

Updating a Heroku deployment

To update a Heroku deployment that was created with the button above, you may first set up a git repo to push to Heroku

$ heroku login
$ git clone https://github.com/tryretool/retool-onpremise
$ cd retool-onpremise
$ heroku git:remote -a YOUR_HEROKU_APP_NAME

To update Retool (this will automatically fetch the latest version of Retool)

$ git commit --allow-empty -m 'Redeploying'
$ git push heroku master

Manually setting up Retool on Heroku

You may alternatively use the following following steps to deploy to Heroku

  1. Install the Heroku CLI, and login. Documentation for this can be found here: https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up
  2. Clone this repo git clone https://github.com/tryretool/retool-onpremise
  3. Change the working directory to the newly cloned repository cd ./retool-onpremise
  4. Create a new Heroku app with the stack set to container with heroku create your-app-name --stack=container
  5. Add a free database: heroku addons:create heroku-postgresql:hobby-dev
  6. In the Settings page of your Heroku app, add the following environment variables:

    • NODE_ENV - set to production
    • HEROKU_HOSTED set to true
    • JWT_SECRET - set to a long secure random string used to sign JSON Web Tokens
    • ENCRYPTION_KEY - a long secure random string used to encrypt database credentials
  7. Push the code: git push heroku master

To lockdown the version of Retool used, just edit the first line under ./heroku/Dockerfile to:

FROM tryretool/backend:X.XX.X

Render

Render is a unified platform to build and run all your apps and websites with free SSL, a global CDN, private networks and auto deploys from Git. You can deploy Retool on Render in one click through their repo here.

Troubleshooting

I get redirected to login page on sign up

If you didn't go through the process of provisioning a domain name and want to access your Retool instance via the IP of the machine (which is perfectly reasonable, especially during a trial) you need to add the COOKIE_INSECURE=true environment variable in the docker.env file. This just enables authentication cookies to be sent via HTTP.

Make sure to run sudo docker-compose up -d after modifying the docker.env file.

I want to use a private IP of the machine, not the default public one

No problem. When you run ./install.sh, instead of just clicking enter, type in your private IP. If you want to change this after it has already been set, modify the DOMAINS variable in the docker.env file.

I'd like a hand with this

Happy to help - please book a time with one of our engineers here!

Updated 13 days ago


Setup


Setup Retool in your own VPC.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.