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
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
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
nginx with your package manager.
Copy nginx-example.conf to
nginx-example.conf may be renamed to anything, such as
example.com.conf. You'll need to make the following changes.
server_namelines should match the DNS hostnames for your Sandstorm install.
ssl_certificate_keyto 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
BIND_IP settings should look like this.
Then, configure Sandstorm to use your new base URL and wildcard host. Here is an example pair of
/opt/sandstorm/sandstorm.conf for a Sandstorm server that would be accessed by visiting
example.com over HTTPS.
If you are serving HTTPS or HTTP on non-default port numbers, then you will need to add a port
number to both
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.
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
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.