servemd

README

servemd

servemd is an minimalist HTTP server which supports markdown, pug (formerly jade), authentication for secured paths, caching, and TLS. Files are served in accordance with their MIME type, allowing for native viewing (e.g. PDFs or videos on mobile). The example directory shows typical usage (viewable live here), which could look as follows:

.
├── secret         #(you can require auth for this dir)
│   └── index.md   # /secret
├── index.md       # / or /index
├── page.html      # /page.html or /page
├── paper.pdf      # /paper.pdf or /paper
└── video.mp4      # /video.mp4 or /video

Installation

Standalone

servemd can easily be installed as an executable. Download from the latest compiled binaries and put it anywhere in your executable path (e.g. /usr/local).

Source

To install servemd from source, you need to have a Go development environment. If you've done Go development before and your $GOPATH/bin directory is already in your PATH:

go get github.com/lucasem/servemd

Usage

To run the server, simply run:

servemd settings.yaml

The settings.yaml file specifies all configuration information for the server. The only required field is dir, the path to serve.

dir: path/to/docs              # required
port: 8080                     # optional, defaults to 80
host: localhost                # optional, defaults to kernel-reported hostname
log: server.log                # optional, log file; defaults to stderr
template: path/to/md.tpl       # optional, but you should set it
ttl: 240                       # optional, defaults to 0 (in minutes)
secrets:                       # optional
  my_dir: my_password
  other_dir: other_password
tls:                           # optional
  cert: fullchain.pem          # TLS required
  privkey: privkey.pem         # TLS required
  only: false                  # optional, defaults to false
  required: secrets            # optional, 'all', 'secrets', or 'none' (default)
  port: 8443                   # optional, defaults to 443

Markdown and Pug(/Jade)

Markdown is parsed using blackfriday's MarkdownCommon implementation, which features common extensions including fenced code blocks and strikethroughs. Syntax highlighting can be done easily with Prism in the markdown template.

The template file uses the format described in text/template with {{ .Content }} substituted by the HTML from rendered markdown. See the example template.

Pug files are automatically rendered before a request is served.

Caching

Caching is enabled by setting ttl to a non-zero value (in minutes). If ttl is negative, the cache will never expire any cached response. The cache can be forced to empty by sending SIGUSR1 to the servemd process:

$ killall -USR1 servemd

Caching is particularly useful when serving markdown and pug files, because these files will never have to be re-rendered (dramatically reducing response time) until they expire.

Secrets and Authentication

servemd authenticates using HTTP Digest Access Authentication (RFC 2617). The username isn't affirmed, only the password needs to match.

TLS

The configuration servemd uses for TLS yields an A+ on SSL Labs!

When specifying TLS, two servers (one HTTP and one HTTPS) will be spawned unless tls.only is set to true.

The required option, when set to all, will redirect all HTTP traffic to use HTTPS. When set to secrets, this is only done for traffic that hits a secret path (if at least this isn't set, then your secrets may not be very secret because it's very easy to read HTTP traffic over wifi).