Self hosting FAQ

Frequently Asked Questions from people running their own Sandstorm

One way to use Sandstorm is to run the software on your own server.

How do I log in, if there's a problem with logging in via the web?

If logging into your Sandstorm server over the web isn't working, you can reset your Sandstorm's login providers. Resetting login providers will retain all existing accounts, including account metadata such as who is an admin.

These instructions assume you've installed Sandstorm as root, which is the default recommendation. If not, remove the sudo from the instructions below.

• Use e.g. ssh to log into the server running Sandstorm.

• Run this command to deconfigure all existing OAuth-based login providers.

    sudo sandstorm reset-oauth
  

  On success, it will print:

  reset OAuth configuration
  

• Run this command to generate a token you can use to log in as an admin, for emergency administration.

    sudo sandstorm admin-token
  

  This will print a message such as:

  Generated new admin token.
  
  Please proceed to http://sandstorm.example.com/admin/19bc20df04838fdc03101d898be075cc02de66f2
  in order to access the admin settings page and configure your login system. This token will
  expire in 15 min, and if you take too long, you will have to regenerate a new token with
  `sandstorm admin-token`.
  

• Visit the link it printed out, which gives you emergency access to the server's admin panel.

• From there, configure the login providers of your choosing.

• Now, log in as yourself. If you log in as the first user that ever signed into this Sandstorm instance, then you will be an admin.

Why does Sandstorm require a wildcard host?

See Why Sandstorm needs a wildcard host.

Why can't I access Sandstorm from the Internet, even though the server is running?

If your sandstorm.conf looks like this:

SERVER_USER=sandstorm
PORT=6080
MONGO_PORT=6081
BIND_IP=127.0.0.1
BASE_URL=http://mydomain.com:6080
WILDCARD_HOST=*.mydomain.com:6080
MAIL_URL=
UPDATE_CHANNEL=dev

then you need to change the BIND_IP value to 0.0.0.0.

(To be pedantic, this the unspecified IPv4 address. For IPv6 compatibility, you may want :: instead. I haven't tested this yet.)

What ports does Sandstorm need open?

If you have a strict firewall around the server running Sandstorm, or you are at home and have to enable "port forwarding" on a home wifi gateway, here is a list of the ports Sandstorm needs. This applies on cloud providers like Amazon EC2, where the defaults allow no inbound traffic.

Default configuration

• TCP port 6080

Optionally

• TCP port 443
• TCP port 80

What are the minimum hardware requirements?

You'll need an amd64 (aka x86_64) computer with about 1GB of RAM and 5 GB of disk space. You can probably get away with less, but I wouldn't advise it.

Using a virtual machine from Amazon EC2, Google Compute Engine, Linode, Digital Ocean, etc., is fine; just make sure you have a recent Linux kernel. Ubuntu 14.04 is an easy and good choice of base operating system.

Sometimes I randomly see a lot of errors across the board, while other times the same functions work fine. What's going on?

Do you have enough RAM? Linux will start randomly killing processes when it's low on RAM. Each grain you have open (or had open in the last couple minutes) will probably consume 50MB-500MB of RAM, depending on the app. We therefore recommend using a server with at least 2GB. If you have less that that, see the next question.

My virtual machine doesn't have that much RAM, what can I do?

It might help to set up swap space. The following commands will set up a file on-disk to use as swap:

dd if=/dev/zero of=/swap.img bs=1M count=1024
mkswap /swap.img
swapon /swap.img

echo /swap.img swap swap defaults 0 0 >> /etc/fstab

Why do I have to log in through Google or Github? Doesn't that defeat the point of the IndieWeb?

In short, because we actually think this is the most secure option we can provide right now, though we want to do better eventually.

A note about when and why we think security is important:

• It's a design goal for us that self-hosted servers be as secure as possible.

• For a development instance only accessible to localhost, login security may not be particularly important. There's discussion of how to move forward on this GitHub issue.

• For Sandstorm instances maintained for public use, such as the Sandstorm alpha site, we believe account security is essential.

Passwords have a lot of problems. People choose bad passwords. People -- even smart people -- are often fooled by well-crafted phishing attacks. And, of course, people regularly forget their passwords. In order to deal with these threats, we believe that any password-based login system for Sandstorm must, at the very least, support two-factor authentication and be backed by a human security team who can respond to hijackings. There must also be an automated password reset mechanism which must be well-designed and monitored to avoid attacks. Unfortunately, we don't have these things yet. Moreover, we don't believe that building a secure password login system is the best way for Sandstorm to deliver something interesting to the ecosystem.

Another problem with password login is that it makes federation more complicated. When you federate with your friend's server, how does it authenticate you? Not by password, obviously. Perhaps by OpenID or OAuth, but that is again a thing we would need to implement.

For now, by relying on Google and Github for login, we get top-notch security and straightforward federated authentication with very little work. This lets Sandstorm be focused on what it's good at. (We could add Twitter, Facebook, etc. login as well, but we are worried about people forgetting which one they used and ending up with multiple accounts.)

We don't want things to stay this way forever. One way to address this is by building GPG login so you can create an account based on your public key. We're tracking that in this issue.

Why do I see an error when I try to launch an app, even when the Sandstorm interface works fine?

When Sandstorm seems to be working fine, you might find that launching an instance of an app (in Sandstorm terms, a "grain") gives you a browser error window. For example you might see this error screen:

even when the app management interface seems to work fine:

This probably relates to Sandstorm's need for wildcard DNS. Sandstorm runs each app session on a unique, temporary subdomain. Here's what to check:

• Make sure the WILDCARD_HOST has valid syntax. In the Sandstorm config file (typically /opt/sandstorm/sandstorm.conf, look for the WILDCARD_HOST config item. Note that this should not have a protocol as part of it. A valid line might be:

WILDCARD_HOST=*.yourname.sandcats.io:6080

• Make sure wildcard DNS works for your chosen domain. See also this issue in our repository. If setting up wildcard DNS is a hassle for you, consider using our free Sandcats dynamic DNS service for your WILDCARD_HOST.