Proxying Unstack on the same domain as your web app

Hosting your web application and Unstack site on the same domain.

WARNINGS:

This document requires advanced knowledge and must be followed in its entirety. Not following this properly may cause your site to not act properly.

NOTES:

You will need to be currently subscribed to Full+

Unstack does not have developers on their support team, so if you think you'll need help/verification with/of proper configuration please contact us 5 business days before you'd like to go live so we have time to have a developer review your code. What do I send to support?

What is proxying?

Proxying, specific to Unstack is the ability to use the site you create in Unstack on your domain where you are already running a web application.

Details / Use Case

In some cases, companies have a hard requirement their web application be on the root domain of their website (e.g. https://yourapp.com). Unstack provides options to proxy web traffic to your root domain to give you the best of both worlds. Note, this is advanced functionality and typically requires an engineer to set up.

Steps Pre-Server Implementation

  1. Your first step will be setting up your custom domain within the application in order to generate the DNS records that you'll need to add to your DNS registrar.

    Begin this process by going to the settings page within the app and selecting custom domain:

  2. Next, once the drawer opens you'll input your domain name which may follow the following format: [prefix].[root].[suffix], thus, this domain would be accepted: www.example.com and subdomain.example.com, however, these would not be: www.subdomain.example.com or example.com.


    Once you've entered the domain, click "Set domain" this will generate the first DNS record.

  3. Next, if you're on a paying plan, you'll have the choice to enable SSL which we highly recommend if applicable. You can enable this by clicking "Add SSL".


    Once you've gone through the process of generating those records you should see the following:

  4. Contact Unstack Support and request your Site Connection be switched to Proxying
  5. Follow the steps below to configure proxying within your respective server:
    1. Nginx
    2. Ubuntu
    3. Apache

Friendly note: If your server isn't listed, let us know and we can help out!

Web Server Implementations


Nginx

location /app {
# Point to internal resource
}
location / {
proxy_set_header Host $host;
proxy_set_header X-Proxy-Host $host;
proxy_set_header X-Proxy-Forwarded-For $remote_addr;
proxy_pass https://YOURSITE.unstackproxy.com/$request_uri;
}

What these mean:

  1. Host tells the Unstack load balancer the URL your visitors are hitting on your web server. This will get overridden by the load balancer, but it’s important to pass this if you’re using an HTTP scheme, as the load balancer may otherwise return a redirect to an HTTPS scheme.
  2. X-Proxy-Host tells Unstack the URL your visitors are hitting on your web server. This helps us tie your traffic to your site.
  3. X-Proxy-Forwarded-For tells Unstack the IP address of your visitors’ browsers so that we can properly record the analytics for them.

Operating System Considerations

Depending on your operating system, there’s a chance you may also need to handle domain resolution in the proxy process.

Ubuntu

For Ubuntu, you’ll probably need to set up a resolver in /etc/nginx/nginx.conf:

http {
        resolver 127.0.0.1;

You may also have to install dnsmasq as a handler for the DNS resolution.

sudo apt install dnsmasq

In other flavors of Linux, or if you’re using Docker containers, you may have to disable conflicting resolvers.

Apache

Apache requires the mod_proxy module to be installed, and the configuration looks like this:
<Location "/path-to-page">
ProxyPass https://{subdomain}.unstackproxy.com/path-to-page
ReverseProxyPass https://{subdomain}.unstackproxy.com/path-to-page
ProxyAddHeaders On
ProxyPreserveHost On
</Location>
Another note for the reverse-proxy configuration article. We should tell people to reverse-proxy all of the following paths:
  • /sprk/pv
  • /sprk/ev
  • /sprk/fp
  • /sprk/up

If you do not include these paths: forms will not submit to Unstack and your analytics will not render. We have no way of retrieving the missing data.

Need help? Here's what to send us—

Help with proxying can take up to 5 business days for a response since developers are not directly a part of the support team.

Send in an email to help@unstack.com:

  • Server Type
  • Code Written/Used so far
  • Current Behavior
  • Expected Behavior
  • Applicable Information we should know about, e.g.:
    • other apps running on this server