This document helps you configure Sandstorm to share port 80 (HTTP) with other services on the same machine, or port 443 (HTTPS) with other services. It allows you to use a custom domain name, without an ugly port number such as :6080 in your URLs, and optionally with HTTPS.

If you use this document to set up HTTPS, note that you are in charge of obtaining and renewing your HTTPS certificates. This tutorial works properly with certificates you purchase, or with self-signed SSL. If you want free, auto-renewing sandcats.io HTTPS certificates, you will need to use sniproxy instead of nginx; see the note at the bottom of the HTTPS overview page.

If you have problems with apps seeming to constantly reload themselves, you might need to read about WebSocket connections in our FAQ.

Configuring nginx and Sandstorm for reverse proxying

nginx optional: Apache2 and other choices available

This tutorial covers the use of nginx. If you prefer Apache2 or another reverse proxy, you can read this document to get an overview.

For Apache2 in particular, feel free to use our sample VirtualHost configuration for Apache2 Sandstorm requires WebSockets support; to enable that, make sure to pay attention to the RewriteRule stanzas in the example configuration.

If you use a non-nginx, non-Apache2 reverse proxy, we'd love for you to contribute a pull request with example configuration files.

HTTPS or not: you choose

When running Sandstorm behind a reverse proxy such as nginx, you can configure HTTPS in the reverse proxy.

This tutorial provides links to sample configuration files where relevant. The example files configure nginx to listen on ports 80 (HTTP) and 443 (HTTPS). On port 443, nginx routes the traffic to Sandstorm; on port 80, nginx serves a HTTP redirect to upgrade the request to HTTPS.

If you prefer to not use HTTPS, read the example configuration files and look for comments that indicate what changes to make.

Create DNS entries

If you are going to run Sandstorm at example.com, you may need to create a DNS record for example.com. You will usually also need to add a wildcard DNS record for *.example.com. You can read more about wildcard DNS for Sandstorm.

Prerequisites for HTTPS

Obtain or generate a key and TLS certificate with example.com and *.example.com in subjectAltName. You can do that by buying a wildcard HTTPS certificate, following our self-signed certificate authority instructions, or using CloudFlare Origin CA's free wildcard certificates.

If you are using nginx, place the following certificate data in the following paths on your system.

  • HTTPS private key in /etc/nginx/ssl/sandstorm.key. This should be owned by root, permissions mode 0600. To set the permissions, you can run the following commands.

    • sudo chown root.root /etc/nginx/ssl/sandstorm.key
    • sudo chmod 0600 /etc/nginx/ssl/sandstorm.key

  • HTTPS certificate in /etc/nginx/ssl/sandstorm.crt. With nginx, the certificate file should contain the full intermediate certificate chain. This should be owned by root or any other user, and the mode should be 0600 or any other permissions. To set the permissions, you can run the following commands.

    • sudo chown root.root /etc/nginx/ssl/sandstorm.crt
    • sudo chmod 0600 /etc/nginx/ssl/sandstorm.crt

Configure nginx

Install nginx with your package manager.

Copy nginx-example.conf to /etc/nginx/sites-enabled/.

nginx-example.conf may be renamed to anything, such as example.com.conf. You'll need to make the following changes.

  • All server_name lines should match the DNS hostnames for your Sandstorm install.

  • Point ssl_certificate and ssl_certificate_key to your corresponding TLS certificate and key files.

Test your nginx configuration:

sudo nginx -t

Configure Sandstorm's configuration files

First, configure Sandstorm to listen on localhost, port 6080, for HTTP requests. We use port 6080 here to match the example nginx configuration. You will need to edit /opt/sandstorm/sandstorm.conf. Make sure there is no HTTPS_PORT=... line, as the HTTPS_PORT=... configuration option enables Sandstorm's auto-renewing sandcats.io free SSL. The PORT and BIND_IP settings should look like this.

PORT=6080
BIND_IP=127.0.0.1

Then, configure Sandstorm to use your new base URL and wildcard host. Here is an example pair of lines from /opt/sandstorm/sandstorm.conf for a Sandstorm server that would be accessed by visiting example.com over HTTPS.

BASE_URL=https://example.com
WILDCARD_HOST=*.example.com

If you are serving HTTPS or HTTP on non-default port numbers, then you will need to add a port number to both WILDCARD_HOST and BASE_URL. In the example configuration, nginx listens for HTTPS on port 443 and HTTP on port 80, which are the default ports, so you do not need add a port number unless you are doing an unusual Sandstorm install.

Run

Finally, start nginx, and restart Sandstorm to use the new config.

sudo service nginx restart
sudo service sandstorm restart

Test your Sandstorm install

Make sure to test your Sandstorm install by visiting it on the web.

Make sure login works. If you changed your BASE_URL, Sandstorm will temporarily disable any OAuth providers like Google or GitHub so that you can ensure they are configured correctly. Make sure to visit Identity providers in the Admin panel within your Sandstorm install and re-enable them. If OAuth providers were your only way to log in, you might need to get a login token via the command line.

Make sure grains can start. Visit a grain, or create a new one, and ensure it loads properly. If it does not, you might have an issue with wildcard DNS or SSL.