tgvashworth

Here’s an introduction to an project I open-sourced recently: distra. There’s a video, and then a short article about it.

distra is a tool for building websites. Use it to serve static files and directories, and to give servers running on your computer nice URLs. You can set up hosts and routes (directories or proxy targets) using JSON, and then feel like a boss.

It also adds to your hosts file (safely) so you never have worry about that either!

Why?

I had so many servers, particularly serving static files, that I never knew what was being served and on which port. So I built this so I’d never have to care again… and neither will you.

Install

distra requires:

• OS X (yeah, sorry)
• Node
• npm

In your terminal:

$ npm install -g distra
$ distra

Wahey! You’re up.

But it won’t do much yet – you need to configure it.

Configuration

distra is configured from the .distra.json file in your home directory, but you don’t ever have to touch this file if you don’t want to.

Adding a host

To add a host, use distra add.

$ distra add [host] [directory or url]

The host and directory or url are both optional. If you omit the directory or url distra will serve your current directory.

If you omit both, distra will serve the current directory with the name of the directory as the host.

Try it:

Head to a directory with some .html files in it, lets say it’s called website.

$ distra add

Assuming distra is started (just use distra), you will find that you can go to http://website:9876/ and access those files.

distra is servering the website directory from the URL http://website:9876/. Neat, huh?

Note: If you’re running distra without sudo (so it’s not running on port 80), then you’ll need to add all of these URLs to your hostsfile. To avoid this, run distra on port 80. How to do this is outlined in the ‘tips’ section.

Removing a host

To remove a host, use distra rm.

$ distra rm [host]

Again, host is optional - by default, it will just use the directory name.

The config file

The config file will generally be found at ~/.distra.json.

Here’s an example.

{
  "mysite.dev":   "localhost:4000",
  "project":      "/Users/you/sites/project"
}

In the example above, requests made to http://mysite.dev/ will be proxied through to the server running on port 4000 (a Jekyll server, perhaps). Requests made to project will be served static files from the directory specified.

You can view your current config using distra:

$ distra config

Tips

Here’s a couple of tips to help you out:

Ports

You can specify the port on which you want distra to start.

$ distra 1337

Portsaway!

I recommend starting distra on port 80 so you don’t have to mess around with ports and your hostsfile!

$ sudo distra 80

Finally

distra has become an integral part of my workflow – let me know if you use it, like it or come across any bugs!