Quick Start

AssetServer was designed to have intelligent defaults so that new users could get up and running quickly without needing to understand much of what is going on behind the scenes. The following concepts will help to understand what is going on:

  • AssetServer manages a tree of resources just like a webserver. Most simple installations will just have a single physical directory mounted at the webserver root. However, it is straightforward to glue together a namespace from multiple (potentially overlapping) physical directories by mounting locations into the web namespace.
  • AssetServer maps filters to physical files. Whenever a resource is requested, the corresponding physical file is found and a configurable set of filters is applied to it.
  • AssetServer operates in two modes: server and build. In server mode, resources can be requested just as with a normal webserver. In build mode, the generated resources can be copied (snapshotted) to some other physical location, allowing them to be served by any webserver that can serve static files.
  • The default filter for many file types is "Embedded JavaScript." This JavaScript-based domain specific language acts as a pre-processor for the resource. A full understanding of this DSL is not required for most situations.

Download and Verify

Download the latest binaries (if on Windows, download the *-windows.zip file and if on anything else, download *-generic.tar.gz) or source distribution from http://www.rcode.net/assetserver/download. Checksums and gpg signatures are available at this location. Gpg signatures can be verified against my public key at the contact page on my blog.

Either add the bin directory to your path or copy the contents to somewhere already on the path.

Get help and verify the version by running:

assetserver version
assetserver help

If you get any kind of errors, ensure the following:

  • That a Java 1.5+ installation is present (run "java -version")
  • If on Windows, the JavaSoft registry keys must be present describing the Java installation
  • If the JAVA_HOME environment variable is present, ensure it points to the correct java installation
  • If assetserver still cannot find the Java installation, set the JAVA_HOME environment variable to the directory that contains "bin/java".

If still having issues, send an email to the author via GitHub.

Start the Server

Create a directory to hold your content and create the config file (the config file is optional, but we will use it later):

mkdir webroot
touch webroot/.asconfig

Start the server:

assetserver serve webroot

The output will be similar to the following:

INFO (assetserver): Starting assetserver version dev (built at 2011-01-16 12:43:24 PST on athena by stella)
INFO (assetserver): Loading server configuration from /Users/stella/tmp/webroot/.asconfig
INFO (assetserver): No mounts configured. Setting up directory /Users/stella/tmp/webroot as server root.
INFO (assetserver): Configuration summary:
Mounts:
  / => ResourceMount(/Users/stella/tmp/webroot)
Root Filters:
  1. NamePatternPredicate(*.js) => Standard Embedded JavaScript Filter
  2. NamePatternPredicate(*.css) => Standard Embedded JavaScript Filter
  3. NamePatternPredicate(*.html) => Standard Embedded JavaScript Filter
  4. NamePatternPredicate(*.js) => YUI JavaScript Optimizer
  5. NamePatternPredicate(*.css) => YUI CSS Optimizer
  6. NamePatternPredicate(*.svg) => SVG Render Filter

INFO (httpserver): Starting HTTP server on port 4080 (all addresses)

Without further configuration, the server starts with a fair number of details. Some configuration is done via the .asconfig file (see the user's guide) and other is done on the command line. To see command line options, run:

assetserver help serve

Add Some Content

Create a file webroot/test.html with the following content:

##EJSON
##=
function summarizeParameters() {
	var k,v,s='';
	for (k in params) {
		v=params[k];
		s+=k+'='+v+'\n';
	}
	return s;
}
##=
<!DOCTYPE html>
<html>
<body>
	The time at generation is #{new Date()}
	<br />
	Parameters:
	<pre>#{summarizeParameters().toHtml()}</pre>
</body>
</html>

Access the resource by pointing your web browser to http://localhost:4080/test.html

AssetServer resources can be parameterized by mangling the name with a special syntax similar to a query string but intended to produce legal filenames that can then be served statically by standard web servers. For example:

Explanation of test.html

test.html uses several EJS constructs:

A full treatment of EJS is available in the user's guide, but here are some highlights of additional builtins:

All builtins that operate on resources (read, include, etc) explicitly manage caching such that you can always be guaranteed that saving a deeply nested resource will cause the regeneration of all parent resources.

Create a Snapshot

Typically, development will proceed directly using the "assetserver serve" web server, but for a production deployment, it is recommended to snapshot all or part of your development tree by using the "assetserver cp" command.

There are several options available to the cp command and full help is available with "assetserver help cp". The simplest form just dumps the processed version of the resource tree to a directory:

mkdir htdocs
assetserver cp webroot htdocs

After running this, the htdocs directory will contain the generated versions of every resource accessible by the configuration.

Mounting Other Locations

Typically, I will have multiple source locations that I would like to link together into one unified view. I can do this with assetserver mounts. By default, if no mounts are explicitly configured, the server will mount the server root directory as the root path (/). Add mounts by modifying the .asconfig file created earlier:

mount('/', '.');	// Add explicit root mount
mount('/myutils', '../libs/myutils');

This adds an explicit root directory mount and then mounts some utilities under the /myutils path. Note that all filesystem paths in the .asconfig file are relative to the directory containing the .asconfig file. The file itself is just a JavaScript source file with various builtins that exist for configuring the server.