ws

README

ws

A nimble webserver with friends

ws started as a nimble static content webserver. It grew some friends along the way. Now it is a small collection for command line utilities.

ws has friends

ws is simple static content webserver with optional support for SSL. It is careful to avoid dot files and by default with server the content of the directory where it is launch. ws has a companion webserver named wsjs. It is adds the ability to dynamic create content via JavaScript files. Each JavaScript file becomes a route itself. wsjs is handy when you're mocking up services or RESTful API.

ws and wsjs have friends. These are additional command line utilities useful for quickly prototyping websites. They include wsinit which creates a project directory skeletons and configuration interactively, wskeygen which generates self signed SSL certificates. Additional commands that are helpful in preprocessing text or augmenting shell scripts.

The complete list of utilities

• ws a nimple webserver for static content
  • Built on Golangs native http/https modules
  • Restricted file service, only from the docroot and no "dot files" are served
  • No dynamic content support
  • Quick startup, everything logged to console for easy debugging or piping to a log processor
• wsjs a nimple webserver for static and JavaScript generated dynamic content
  • built on Robert Krimen's excellent otto JavaScript VM
  • Mockup your dynamic content via JavaScript defined routes (great for creating JSON blobs used by a browser side demo)
• wsinit will generate a project structure as well as a shell script for configuring ws and wsjs in a 12 factor app manor.
• wsmarkdown renders markdown as HTML
  • this markdown is built on the Blackfriday Markdown library
• shorthand a domain specific language that expands shorthand labels into associated replacement values
• slugify turns text phrases into readibly URL friendly phrases (e.g. "Hello World" becomes "Hello_World")
• unslugify returns slugs into simple phrase (e.g. "Hello_World" becomes "Hello World")

Got an idea for a new project? Want to prototype it quickly?

1. run "wsinit" to set things up
2. run ". etc/config.sh" seed your environment
3. run "ws" and start working!
4. run "wsjs" to mockup a RESTful service

ws feature set has been kept minimal. Only what you need when you turn it on.

• Restricted file service, only from the docroot and no "dot files" are served
• No dynamic content support unless you turn on OttoEngine for JavaScript defined routes (great for creating JSON blobs used by a client side demo)
• Quick startup, everything logged to console for easy debugging or piping to a log processor

USAGE

    ws [options]

OPTIONS

-D	(defaults to ) This is your document root for static files.
-H	(defaults to localhost) Set this hostname for webserver.
-O	(defaults to ) Turns on otto engine using the path for route JavaScript route handlers
-P	(defaults to 8000) Set the port number to listen on.
-cert	(defaults to ) path to your SSL cert pem file.
-docroot	(defaults to ) This is your document root for static files.
-h	(defaults to false) This help document.
-help	(defaults to false) This help document.
-host	(defaults to localhost) Set this hostname for webserver.
-key	(defaults to ) Path to your SSL key pem file.
-o	(defaults to false) When true this option turns on ottoengine. Uses the path defined by WS_OTTO_PATH environment variable or one provided by -O option.
-otto	(defaults to false) When true this option turns on ottoengine. Uses the path defined by WS_OTTO_PATH environment variable or one provided by -O option.
-otto-path	(defaults to ) Turns on otto engine using the path for route JavaScript route handlers
-port	(defaults to 8000) Set the port number to listen on.
-tls	(defaults to false) When true this turns on TLS (https) support.
-v	(defaults to false) Display the version number of ws command.
-version	(defaults to false) Display the version number of ws command.

Tour

http support

Make sure ws is your path. To run for basic http service change to the directory you wish to serve and type ws at the command prompt. Example -

    cd public_html
    ws

When ws starts up you'll some configuration information and the URL that it is listening for. Notice the default port is 8000 so you need to include that part in your URL too. If your machine was named example.local then you the URL might look like "http://localhost:8000". Point your web browser at the URL you see for your system. When the web browser connections you should see a stream of log information. The stream of text will continue as long as you continue to have requests to the server until you shutdown ws. To shutdown ws you can press the "ctrl" key and letter "c". This will kill the process and shutdown your web server.

You don't have to run ws with the defaults. You can specity a different document root with the -docroot option. Here is an example of telling ws to use the /www directory for the document root.

    ws -docroot=/www

You can also pass these setting via your operating system's environment. Here is an example of configuration the above setting in a Bash script.

    WS_DOCROOT=/www
    ws

More typically you'll create a configuration file, source it (E.g. in your .profile or .bashrc setup files) and ws will pickup the settings that way.

    #!/bin/bash
    export WS_DOCROOT=/www

If that was sourced in our login scripts then typing ws on the command line would server the contents of /www by default. You can override the defaults with the command line option -docroot.

In this way you can configure hostname, port. In the following example the port will be set to 8081 and the hostname will be "localhost".

Command line version

    ws -docroot=/www -host=localhost -port=8081

The envirnonment version

    #!/bin/bash
    export WS_DOCROOT=/www
    export WS_HOST=localhost
    export WS_PORT=8081

Source the script above then run ws.

    ws

If you have the environment variables set and use a command line option the command line option will override the event variable setting. In the example ws will listen on port 8007.

    #!/bin/bash
    WS_DOCROOT=/www
    WS_HOST=localhost
    WS_PORT=8080

Now run ws

    ws -port=8007

For a full list of command line options run ws with the -help option.

The environment variables for http service are

• WS_DOCROOT
• WS_HOST
• WS_PORT

https support

If you want to run with https support it works on the same principles as http support. It requires three additional pieces of information.

1. It needs to knows where to find your cert.pem
2. It needs to know where to find your key.pem
3. It needs to know to use SSL/TLS support.

By default ws will look for cert.pem and key.pem in your $HOME/etc/ws directory. You can specify alternate locations with the -cert and -key command line options or the WS_CERT and WS_KEY environment variables. To turn https support on you need the option -tls=true or the environment variable WS_TLS set to "true".

Command line example

    ws -tls=true -cert=my-cert.pem -key=my-key.pem

The environment version

    #!/bin/bash
    export WS_CERT=/etc/ws/cert.pem
    export WS_KEY=/etc/ws/key.pem
    export WS_TLS=true

If this was sourced in your login scripts then by default ws will run as a https server with the document root set to your current working directory for your current hostname on port 8443.

Generating TLS certificates and keys

ws comes with a wskeygen option for generating self-signed certificates and keys.

    wskeygen

This was create a cert.pem and key.pem files in $HOME/etc/ws directory.

Otto

otto is a JavaScript virtual machine written by Robert Krimen. The ottoengine allows easy route oriented API prototyping. Each JavaScript file rendered in the Otto virtual machine becomes a route. E.g. example-1.js becomes the route /example-1. example-1 should contain a closure which can recieve a "Request" and "Response" object as parameters. The "Response" object is used to tell the web server what to send back to the browser requesting the route.

    /* example-1.js - a simple example of Request and Response objects */
    (function (req, res) {
        var header = req.Header;

        res.setHeader("content-type", "text/html");
        res.setContent("<p>Here is the Header array received by this request</p>" +
            "<pre>" + JSON.stringify(header) + "</pre>");
    }(Request, Response));

Assuming ottoengine is turned on then the page rendered should have a content type of "text/html" with the body shoulding the paragraph about exposing the request headers as a JSON blob. Two command line options or environment variables turn ottoengine on.

Want to expand out the site quickly, write the HTML skeleton with markdown, sprinkle in some shorthand which can leverage some shell logic and now you have HTML pages with common nav, headers, and footers.

LICENSE

copyright (c) 2014 - 2015 All rights reserved. Released under the Simplified BSD License