Usage

Serve the current directory

The simplest usage of srvdir is to serve the files in the current directory. It's actually this easy.

$ ./srvdir

After you run the command, you should see srvdir's UI display the public URL where it's serving the files in your current directory. srvdir will generate a random URL for you, but don't worry, we'll learn how to customize that next.

srvdir by @inconshreveable

Serving                                                                                     
https://a7ed5771.srvdir.net -> .

Serve a specific directory

To tell srvdir to serve files in a different directory, just pass it the path of the directory you want to serve.

$ ./srvdir /path/to/directory

Serve on a custom subdomain

Instead of letting srvdir generate random URLs for you, you can prefix the path you want to serve with the custom name you want to use, separated with a colon, like so:

$ srvdir custom:/path/to/directory

After which you'll see:

srvdir by @inconshreveable

Serving                                                                                     
https://custom.srvdir.net -> /path/to/directory

Add a username and passowrd

srvdir allows you to specify a username and password to protect your file server so that you can control who has access. Use the -auth flag to do it:

$ ./srvdir -auth="root:12345" custom:/path/to/directory

Now, when someone tries to access https://custom.srvdir.net they'll need to enter the correct username and password to get access.


Serving multiple directories

srvdir lets you serve an arbtriary number of directories simultaneously by adding additional paths to the command line.

$ srvdir foo:/my/favorite/folder bar:/path/to/directory

Will cause srvdir to serve:

srvdir by @inconshreveable

Serving                                                                                     
https://foo.srvdir.net -> /my/favorite/folder
https://bar.srvdir.net -> /path/to/directory

Serving static websites

Hello World

srvdir follows the same conventions other popular webservers follow and will serve the file at index.html if you access the containing folder. To try it, save a new file, index.html in your current directory and type in these contents:

<h1>Hello world!</h1>

Then start srvdir pointing to your current directory:

$ ./srvdir .

Now, in your browser, try opening up the srvdir URL. Instead of seeing a directory listing including index.html, you should see:

Disabling index rendering

Sometimes, the behavior of automatically rendering index.html isn't what you want, so it's easy to turn off, just set the flag -index=false on the command line:

$ ./srvdir -index=false .

If you look at the srvdir URL this time, you should see the familiar directory listing again.

Advanced Features

Uploading and Deleting files

srvdir is really good at serving files, but it can also let clients upload or delete files in the directories you serve. This behavior is disabled by default, but you can turn it on by using the -readonly flag. You probably only ever want to disable readonly mode when you are serving with authentication.

$ ./srvdir -auth="user:password" -readonly=false writeable:.

Once srvdir is running, you can upload a file with an HTTP PUT request:

$ curl -X PUT -d @file.txt https://writeable.srvdir.net/file.txt

And similarly, you can delete afterwards with an HTTP DELETE request:

$ curl -X DELETE https://writeable.srvdir.net/file.txt

Customize directory listing presentation

srvdir exposes a -template option so that you can customize the look and feel of the directory listing without modifying the srvdir code. You must pass a path to a template file in the form specified by Go's html/template package. This is the default template that srvdir uses:

<!doctype html>
<html>
  <body>
    <h3>Directory listing for {{.Name}}</h3>
    <pre>
{{ range .Contents }}<a href="{{.}}">{{.}}</a>
{{ end }}
    </pre>
  </body>
</html>