Skip to main content

Running with a Proxy

Posit Connect can be run behind a proxy server. The proxy server needs to be configured so it correctly handles traffic to and from Posit Connect. This section describes how to configure NGINX or Apache HTTPD as a reverse proxy in front of Posit Connect.

Posit Connect needs to receive the original request URL from the reverse proxy so that it can generate fully-qualified URLs and return them to the requesting client. We recommend that proxies add an X-RSC-Request header to requests. The value of the X-RSC-Request header should be the absolute URL of the original request made by the client (e.g. https://connect.proxy.company.com/some/path/).

Some proxies (like Amazon Web Services Elastic Load Balancer, for example), do not make it possible to add custom headers. If the X-RSC-Request header is not supplied, the standard headers X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port are used in a “best effort” attempt to determine the original request URL.

The X-Forwarded headers are not appropriate when the proxy performs path rewriting (e.g. serving beneath https://proxy.company.com/rsc/). Use X-RSC-Request when path-rewriting. X-RSC-Request takes precedence when both X-RSC-Request and the X-Forwarded headers are supplied.

Use the proxied URL as your Server.Address configuration setting.

/etc/rstudio-connect/rstudio-connect.gcfg
[Server]
Address = https://connect.proxy.company.com/

If your proxy secures traffic with SSL, but uses an insecure (HTTP) connection to Posit Connect, users of the Posit Connect dashboard may receive a warning stating that Connect is being accessed over an insecure connection. The HTTP.NoWarning setting disables this warning.

/etc/rstudio-connect/rstudio-connect.gcfg
[HTTP]
NoWarning = true
NoteAdditional secure proxy settings

If your proxy handles SSL/TLS termination, see Terminate TLS at a proxy for complete guidance on configuring HTTP.ForceSecure, cookie security, and network trust considerations.

To support Shiny, Streamlit, Bokeh, and Panel apps, the proxy should pass websocket connections through to Posit Connect.

Users are able to upload an image to each application. By default the image is limited to 10MB in size. Note that some proxies may be configured to reject uploads of excessive size. Modify the image size limitation with the Applications.MaxAppImageSize configuration setting.

/etc/rstudio-connect/rstudio-connect.gcfg
[Applications]
;; Use a 5MB limit
MaxAppImageSize = 5000000

NGINX as reverse proxy

On Ubuntu, a version of NGINX that supports reverse-proxying can be installed using the following command:

Terminal
sudo apt-get install nginx

On Red Hat, you can install NGINX using the following command:

Terminal
sudo yum install nginx

On SUSE, you can install NGINX using the following command:

Terminal
sudo zypper install nginx

Simple configuration

This example configuration lets NGINX act as a reverse proxy to Posit Connect. The configuration does no path rewriting; all requests beneath the URL http://proxy.company.com/ are routed to Connect. The incoming request URI is communicated to Connect using the X-RSC-Request header.

This configuration assumes that Posit Connect running on the same server as the NGINX proxy and listening on port 3939. Update the localhost:3939 references if your proxy and Connect run on different hosts or if Connect is listening on a different port.

/etc/nginx/nginx.conf
http {
  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  server {
    listen 80;

    # Disables checking of client request body size.
    client_max_body_size 0;

    location / {
      proxy_set_header X-RSC-Request $scheme://$http_host$request_uri;
      proxy_pass http://localhost:3939;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_http_version 1.1;
      proxy_buffering off; # Required for XHR-streaming
    }
  }
}

Restart NGINX after any configuration change.

Terminal
sudo systemctl restart nginx

Path rewriting configuration

This example configuration lets NGINX act as a reverse proxy to Posit Connect from beneath a custom path (e.g. /positconnect/). All requests beneath the URL http://proxy.company.com/positconnect/ are routed to Connect; requests without the /positconnect/ prefix are not handled. The incoming request URI is communicated to Connect using the X-RSC-Request header.

This configuration assumes that Posit Connect running on the same server as the NGINX proxy and listening on port 3939. Update the localhost:3939 references if your proxy and Connect run on different hosts or if Connect is listening on a different port.

/etc/nginx/nginx.conf
http {
  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }
  server {
    listen 80;

    # Disables checking of client request body size.
    client_max_body_size 0;

    location /positconnect/ {
      rewrite ^/positconnect/(.*)$ /$1 break;
      proxy_set_header X-RSC-Request $scheme://$http_host$request_uri;
      proxy_pass http://localhost:3939;
      proxy_redirect / /positconnect/;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_http_version 1.1;
    }
  }
}

Restart NGINX after any configuration change.

Terminal
sudo systemctl restart nginx

Apache as reverse proxy

The Apache HTTPD server can act as a reverse proxy for Posit Connect.

Install Apache on Ubuntu:

Terminal
sudo apt-get install apache2

Install Apache on Red Hat:

Terminal
sudo yum install httpd

Install Apache on SUSE:

Terminal
sudo zypper install apache2

Our example configurations will use the Apache modules mod_rewrite, mod_headers, mod_proxy_http, and mod_proxy_wstunnel. Enable these modules with the commands:

Terminal
a2enmod rewrite
a2enmod headers
a2enmod proxy_http
a2enmod proxy_wstunnel

Simple configuration

This example configuration lets Apache act as a reverse proxy to Posit Connect. The configuration does no path rewriting; all requests beneath the URL http://proxy.company.com/ are routed to Connect. The incoming request URI is communicated to Connect using the X-RSC-Request header.

This configuration assumes that Posit Connect running on the same server as the Apache proxy and listening on port 3939. Update the localhost:3939 references if your proxy and Connect run on different hosts or if Connect is listening on a different port.

Depending on the layout of your Apache installation, you may need the Listen and VirtualHost directives in different files.

/etc/apache2/sites-available/rstudio-connect.conf
Listen 80

<VirtualHost *:80>
  RewriteEngine on

  # Disables checking of client request body size.
  LimitRequestBody 0

  # store variable values with dummy rewrite rules
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=http_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  # set header with variables
  RequestHeader set X-RSC-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"
  # unprefixed websocket proxying
  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule ^/(.*) "ws://localhost:3939/$1" [P,L]

  <Location />
    ProxyPass http://localhost:3939/ connectiontimeout=5
  </Location>
</VirtualHost>

Path rewriting configuration

This example configuration lets Apache act as a reverse proxy to Posit Connect from beneath a custom path (e.g. /positconnect/). All requests beneath the URL http://proxy.company.com/positconnect/ are routed to Connect; requests without the /positconnect/ prefix are not handled. The incoming request URI is communicated to Connect using the X-RSC-Request header.

This configuration assumes that Posit Connect running on the same server as the Apache proxy and listening on port 3939. Update the localhost:3939 references if your proxy and Connect run on different hosts or if Connect is listening on a different port.

Depending on the layout of your Apache installation, you may need the Listen and VirtualHost directives in different files.

/etc/apache2/sites-available/rstudio-connect.conf
Listen 80

<VirtualHost *:80>
  RewriteEngine on

  # Disables checking of client request body size.
  LimitRequestBody 0

  RewriteRule ^/positconnect$ /positconnect/ [R]
  # store variable values with dummy rewrite rules
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=h_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  # set header with variables
  RequestHeader set X-RSC-Request "%{req_scheme}e://%{h_host}e%{req_uri}e"
  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule /positconnect/(.*) "ws://localhost:3939/$1" [P,L]

  <Location /positconnect/>
    ProxyPass http://localhost:3939/ connectiontimeout=5
    ProxyPassReverse /positconnect/
    ProxyPassReverse /
  </Location>
</VirtualHost>

Outbound proxy servers

Connect sends outbound HTTP and HTTPS requests through the proxy that the environment variables name. If your network requires a proxy server for outbound access, set the proxy environment variables for the Connect server process. See Setting environment variables via systemd for one way to set them.

Connect reads these environment variables:

  • HTTP_PROXY or http_proxy: The proxy for HTTP requests.
  • HTTPS_PROXY or https_proxy: The proxy for HTTPS requests.
  • NO_PROXY or no_proxy: A comma-separated list of host names, IP addresses, and IP address ranges that bypass the proxy.

Connect reads the variables on its first outbound request. After you change the variables, restart Connect. If both forms are set, a non-empty uppercase value takes precedence. An empty uppercase value falls back to the lowercase form. Connect never sends requests to localhost or to loopback addresses through the proxy.

Requests that use the proxy

Connect sends most outbound requests through the proxy. Examples include:

  • Public content validation requests to https://verify.pct.posit.co/url-validator.
  • Requests to an identity provider for OAuth 2.0 and OpenID Connect (OIDC) login, and OAuth integration token exchanges.
  • SAML IdP metadata download (when SAML.IdPMetaDataURL is set).
  • Requests for GitHub App integrations.
  • Token exchange requests to Posit Package Manager.
  • Content webhook requests.
  • Product check and What’s New feed requests.

Requests that do not use the proxy

Connect does not use the proxy for these requests, even when the variables are set:

  • LDAP connections. Connect opens LDAP connections directly, so the LDAP server must be reachable without a proxy.
  • SMTP connections for email delivery.
  • Connections to the job launcher.
  • Requests to localhost and to loopback addresses.
  • Requests from users to content in off-host (Kubernetes) pods.
  • Avatar image requests to identity provider URLs.

Off-host execution

In off-host execution, Connect sends session checks, pings, and TensorFlow model metadata requests to content pods through the proxy. Add the IP address range of the pod network, or the cluster host names, to NO_PROXY.

Content processes

In local execution mode, content processes inherit the server environment by default. Content code that makes HTTP requests then uses the same proxy settings. To send content requests to internal hosts without the proxy, add those hosts to NO_PROXY. In off-host execution, content does not inherit the server environment, so it does not use the server proxy settings. See Environment variables for details.

Package installation and Git

Connect passes Packages.HTTPProxy and Packages.HTTPSProxy to Git operations and to package installation. For Git operations, Connect sets HTTP_PROXY and HTTPS_PROXY to the setting value. For R package installation, Connect sets http_proxy and https_proxy to the setting value. These settings override the proxy variables inherited by the Connect process for those operations. They do not change the proxy that the running server or content uses.

Public content validation

Connect needs outbound access to https://verify.pct.posit.co/url-validator on port 443 to validate public content. The proxy must not change the request body, the Date header, or the X-Content-Signature header. The validation service checks the signature over the date and the request body. See Public access requirements.

License manager

When Connect runs the license manager, the command inherits the server environment, including the proxy variables. See Proxy servers in the licensing documentation.