Skip to content

Overview

Concepts and Principles

Development

Overview

IDEs

API Explorer

Releases

Release Notes

TORO Integrate

Coder Studio

Coder Cloud

Bug Reports

Search

Proxying an Integrate Package to a Domain

At times, you may find the default URL of your integrations hard to read, too long to remember, or misleading to the client. In cases like these, especially for integrations intended for public-use, it pays to mask the URL in favor of something shorter and more intuitive. This page will guide you on how to to proxy your endpoints so clients can access your TORO Integrate-hosted APIs1 or web pages via friendlier URLs.

Instructions may or may not be applicable depending on your own setup

The procedures in this guide are based on a particular set of assumptions. Depending on your own setup, you may have to tweak variables.

Premise

Our goal is to port the integration accessible at https://integrations.torocloud.com/api/careers/account/create to https://careers.torocloud.com/account/create.

Before proxying the domain

We will assume that a proxy server like NGINX is running in front of TORO Integrate. In order to mask the URL, we will create a proxy URL configuration in the proxy server.

Procedures

  1. Add a CNAME record to your domain's DNS pointing the proxy domain to the original one.

    Name Type Value
    careers.torocloud.com CNAME integrations.torocloud.com
    integrations.torocloud.com A 192.0.2.23

    The original domain is integrations.torocloud.com and the intended proxy for it is careers.torocloud.com. When creating the DNS entry, you actually have two options:

    • Create an A record pointing to the same IP address as integrations.torocloud.com.
    • Create a CNAME record pointing to integrations.torocloud.com.

    The latter is preferable over the former because you won't have to update the IPv4 value of the careers.torocloud.com record if integrations.torocloud.com's IPv4 address changes.

  2. Create the NGINX configuration files.

    The sample configuration below would map the URL integrations.torocloud.com/api/careers to careers.torocloud.com, treating https://careers.torocloud.com as the root path:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    server {
      listen 80;
    
      server_name careers.torocloud.com
    
      location / {
        return         301 https://$server_name$request_uri;
      }
    
      include  /etc/nginx/standard_error_page.conf;
    }
    server {
      listen 443;
    
      server_name careers.torocloud.com
    
      ssl on;
      ssl_certificate       /datastore/vhosts/ssl-certs/careers.torocloud.com.crt;
      ssl_certificate_key   /datastore/vhosts/ssl-certs/careers.torocloud.com.key;
    
      location /assets/ {
          proxy_pass      http://APP_SERVER:APP_PORT1/careers/;
      }
    
      location / {
           proxy_pass                 http://APP_SERVER:APP_PORT1/api/careers/;
           proxy_set_header           X-Forwarded-Host $host;
           proxy_set_header           X-Forwarded-Server $host;
           proxy_set_header           X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header           X-Forwarded-Port   80;
           proxy_set_header           Host $host;
    
           proxy_redirect             http://APP_SERVER:APP_PORT1/api/careers/ http://APP_SERVER:APP_PORT1/;
           proxy_connect_timeout      240;
           proxy_send_timeout         240;
           proxy_read_timeout         240;
           }
    
      include  /etc/nginx/standard_error_page.conf;
    }
    

    As you may notice, the assets are proxied. They are stored in the package and are in /careers instead of /api/careers.

    1
    2
    3
    location /assets/ {
        proxy_pass      http://APP_SERVER:APP_PORT1/careers/;
    }
    

    The root path / also proxies the /api/careers from the orignal server:

    1
    2
    location / {
         proxy_pass                 http://APP_SERVER:APP_PORT1/api/careers/;
    

    Disabling access to the original URL

    With the above configuration, the web UI should be available on both integrations.torocloud.com/api/careers and careers.torocloud.com/. However, to restrict access to the original URL, we can set up a redirect in the proxy server like in the configuration below:

    1
    proxy_redirect             http://APP_SERVER:APP_PORT1/api/careers/ http://APP_SERVER:APP_PORT1/;
    
  3. After saving the NGINX configurations, reload NGINX and try to access the URL. The image below shows that the URL is now careers.torocloud.com.

After proxying a domain

And that concludes this tutorial!