turtle.io is very easy to get up and running! All you need to do is install it, and tell it what directory holds your web sites, & which hostnames to answer for.
You can also create complex web applications, with a familiar API.
Getting Started
Install the module with: npm install turtle.io
Create a script to load & start a server. You could use sample.js in the turtle.io directory (./node_modules/turtle.io) as a template, or see the examples below
[Optional] You can override defaults by passing the factory an Object
The following examples assume you've installed turtle.io into /opt/turtleio, if this is not the case you need to edit the applicable file to correct the path.
Upstart
Use the provided upstart recipe: sudo sh -c 'cp node_modules/turtle.io/turtleio.conf /etc/init; initctl reload-configuration; service turtleio start;'
Systemd
Use the provided systemd service: sudo sh -c 'cp node_modules/turtle.io/turtleio.service /etc/systemd/system; systemctl enable turtleio; systemctl start turtleio;'
What about Windows?
It runs great on Windows, but you're on your own to daemonize it!
Examples
turtle.io requires a default virtual host to be specified, because it is the failover when a request can't be routed.
Virtual hosts
Virtual host keys are the hostname, and the value is the directory relative to "root".
The request object is passed to every route handler as the second argument, will have a body property with the payload from the Client. It will not be coerced to another format, so if you expect JSON, you'll have to JSON.parse() it yourself (for now).
API & decoration
canETag
Function (path, method)
Determines if a path can receive an ETag
etags.ignore
Array
Array of paths to ignore for ETag generation
etags.update
Function (state)
Updates the etag cache with new state
request
allow
String
Allowed HTTP methods
ip
Number
Request IP
parsed
Object
Parsed HTTP request
query
String
Parsed query string
server
Object
turtle.io instance
host
String
Virtual host handling the request.
response
error
Function (status, body)
Send an error response.
redirect
Function (url)
Send a redirection.
respond
Function (body[, status, headers])
Send a response.
send
Function (body[, status, headers])
Send a response.
Configuration
Configuration values can be set by passing an Object to the factory, or any time afterward.
address
String (0.0.0.0)
Network address to listen on.
cacheSize
Number (1000)
Size of LRU cache for Etag validation.
catchAll
Boolean (true)
Handle unterminated requests.
compress
Boolean (true)
Compress responses when supported.
default
String
[Required] Default hostname to handle requests which are not specified within vhosts; must be a valid entry within vhosts.
etags
Object
ETag middleware configuration.
To enable state propagation set notify to true, and when receiving new state pass to etags.update().
{ notify: true, ignore: [], // Array of paths to ignore onchange: (eventName, serializedCache) => { ... // serializedCache needs to be passed to other instances `etags.update()` }, update: serializedCache => { ... // Override if you want to do more than set new state }}
headers
Object
Response headers. CORS is enabled by default.
hosts
Object
[Required] Virtual hosts the server will respond for, key is the hostname & value is the directory relative to root.
index
Array
Files to look for when accessing a directory resource.
json
Number (2)
Default "pretty" ident size
logging
Object
Logging configuration.
logging.enabled
Boolean (true)
Override & disable stdout emitting by setting to false.