Tally-ho! (begin…)

This manual is a pre-release preview. Please follow Moonstalk on Twitter or Facebook to be notified of a public release. If you like running with scissors, you can pull from our public repository on Bitbucket.

Installation

Whoah!

Please be aware that Moonstalk is not suited to the following scenarios. See our Pivotal Tracker project for tasks and fixes in upcoming iterations.

Choose a server

You should be able to run Moonstalk on pretty much any Linux or UNIX-based computer.

Moonstalk is not currently compatible with the Windows OS, and has no roadmap for it.

For best performance when hosting busier sites with VPS hosting, choose a package that includes use of 4 or more cores (1 core is adequate for most sites). This site is being served by Moonstalk running on a 4-core Linode (in London). You can take a peek at the response headers to check this (each request is likely to be served by a different backend, indicated by the last number in the node of the X-Powered-By header).

Install dependencies

Ubuntu, Debian, etcetera

  1. apt-get install libfcgi-dev spawn-fcgi lighttpd lua5.1 liblua5.1-dev luarocks libssl-dev libsqlite3-dev mercurial
  2. update-rc.d -f lighttpd disable; killall lighttpd; mkdir /etc/logrotate.d-disabled; mv /etc/logrotate.d/lighttpd* /etc/logrotate.d-disabled

If default log rotation is not disabled Lighttpd will periodically be restarted without its Moonstalk configuration (it's also started immediately upon install with its default config, which we don't want).

On Debian apparently if you want to run using non-root privileges, you currently need to change the permissions on /sbin/sysctl, or copy it to /bin.

Mac OS X

  1. Install the Homebrew (or MacPorts) package manager.
  2. brew install fcgi spawn-fcgi lighttpd lua51 mercurial openssl libuv

lighttpd is the default webserver. libfcgi and spawn-fcgi are required to interface with the webserver. lua5.1 is the language runtime that Moonstalk uses. libuv is a library for handling connections used by the database .LuaRocks is an optional package manager for Lua modules. mercurial (hg) is required only for installing and updating Moonstalk, but you may use other systems for your own repositories (see Updating). You may manually install any of the above if you prefer.

Install Moonstalk

  1. cd /usr/local
  2. hg clone https://bitbucket.org/moonmill/moonstalk moonstalk
  3. cd moonstalk
  4. ./runner

The ./runner command won't start anything now, but will check for required Lua modules, just hit return to install them (using LuaRocks) when it prompts you. (This may take a while.)

If you prefer you may install modules manually, but ensure you install them in a directory prefix configured in your $LUA_PATH.

If you're setting up a production server, be sure to edit data/configuration/Host.lua before proceeding. Or simply: ./runner hostname=server.example.com logging=0

Ensure that your moonstalk/ folder is not in a public path (e.g. an existing web or FTP server root) and that it is not readable by any non-adminstrators.

Enable the Manager

Moonstalk includes a simple CMS system named Manager, you'll need an administrator login to use it, simpy run ./clerk scribe "manager.Operator()" and it'll give you a new password, on your development machine you can then access the web interface at localhost/Manager.

Settle-in

That's it, now you can start coding or use the installed applications! If you're fairly new to web development or would like a simple introduction to Moonstalk development, read on — otherwise if you're a daring adventurer leap ahead to the learn section.

Editing

Your primary tool for hands-on development with Moonstalk should be a text editor or IDE having syntax hilighting for Lua, HTML and CSS.

If you'll be using localised text it must support a 'no-BOM' encoding option for UTF-8 which most do.

Collaborating

If you're working with multiple colleagues, you can use the Mercurial (hg) distributed concurrent versioning system (dCVS), as used by Moonstalk itself for installation. If you're new to Mercurial, there's a site for that.

…you'll also need a diff utility:

…and somewhere to store your Mercurial repository (a share point):

Tutorial

Ready for a quick hands-on tutorial?! I'm assuming you've never traded your soul for a copy of FrontPage, and know how to hand-code HTML—or at least won't be too scared reading some. If not, open the source view for this page or any other, start reading it and I'll see you back here later.

Before we do anything, you must change your working directory to your moonstalk install folder.

Define a site

Sites are created as sub-folders inside the sites/ folder, each named with the site's (primary) domain.

If you don't have a domain make one up, or use example.com.

Configure DNS

For development and testing on your own computer you must be able to access your site at its domain, but you probably shouldn't change its public DNS records yet.

Rember to disable or remove this entry when you need to access the actual server again. You may need to flush your DNS cache or restart your web browser for changes to take effect.

Instead of editing /etc/hosts you could create a new DNS record like test.example.com and point this to your computer so that you can easily swap between test and production servers.

If you're using OS X I can recommend using HostsWidget to manage your /etc/hosts file.

Start the server

After defining a site, you can start Moonstalk. The following command will start all the servers (web, pages, and db), and enable development mode which disables Moonstalk's page caching — allowing you to see changes as you refresh a page in your browser during development. As you're not yet running a production server to handle heavy loads, only a single page-generation (Scribe) instance is required.

Add static files

Drop any HTML files and any images or other assets e.g. logo.jpg or page.html into the folder and access them in your browser with their full filename e.g. http://example.com/logo.jpg. Static requests are served by the webserver directly, without any processing by Moonstalk.

Any request containing an extension is considered a request for static content, to be served by the webserver directly.

Add dynamic files

With a variable

Let's try a simple page that just displays details of your web browser. This uses dynamic markup inside an HTML file, which we call a view. Dynamic requests are processed by Moonstalk's Scribe (pages) backend.

Any request not containing an extension is considered a request for dynamic content, to be processed by the Scribe.

<p>Your browser is: ?(request.browser)</p>

With a form

Now let's try something a little more interactive. We'll use a form to input our name and display it upon submission, using an alternative if no name has been submitted yet.

<h2>Hello, ?( form.firstname or "have we met?" )</h2>
<p>What’s your name?</p>
<form method="post">
<input type="text" name="firstname">
<input type="submit">
</form>

Define templates

The hello.html file lacks an <html> tag to make it a complete page, because we're now going to put it in a template. This will apply a common layout to all of our test site's files when Moonstalk serves them.

<html>
<head>
<title>My Site</title>
</head>
<body>
<h1>Welcome to my site</h1>
<? scribe.Insert "content" ?>
</body>
</html>

Save data

So now let's try something a little more clever. We'll save a value from a form upon its submission, and then display its saved value. We'll do this by putting code into an additional Lua file which we call a controller.

database = {"mydata",}
<h2>
Saved value:
?( fetch ( mydata.isaved ) or "nothing saved" )
</h2>

<form method="post">
Save a new value: <input type="text" name="myinput">
<input type="submit">
</form>
if form.myinput then
save ( mydata.isaved, form.myinput )
end

Use the log

If you ever lose track of what-on-earth you think should be happening during development, it's useful to see operations step-by-step. In fact you might like to keep the log open whilst developing and it will show what's happening with each request.

if form.myinput then
save ( mydata.isaved, form.myinput )
log.Append( "=======UPDATE:" .. form.myinput )
else
log.Append "=======FETCH"
end

Linux

OS X

Learn…

If you're not too sure about any of the jargon used up til now, you might like to take a ganders at the following glossary, otherwise jump ahead to the learn page to dig into some usage guidance, and then the develop page to for reference and more advanced topics.

Glossary

Although we attempt to avoid using jargon and proprietary terminology, it's useful to understand the naming conventions used to distinguish the various components and concepts.

Server terminology

The [World Wide] Web

The collective identity of one part of the Internet comprising a multitude of server computers that all perform the same function — like Email allows the exchange of messages, or FTP the exchange of files — the web allows the exchange of pages (which may be plain documents, or interactive software interfaces), collected together into zillions of separate web sites. So-named as a web because most of these pages and sites are linked together, enabling association and exploration amongst them.

A 'server' is simply something that accepts and responds to instructions from a ‘client’. These can be computers (hardware), or combinations of operating system and application programs (software) for which the term is used interchangeably (perhaps confusingly).

Web site

A collection of pages that are accessed via a web browser application (i.e. Safari, Internet Explorer, Firefox, Chrome) on your computer, either corresponding to files in a folder from a web server (a statically generated site), or a web application. [Moonstalk hosts web sites, and runs web applications.]

A 'dynamic' page (or site) may refer to either a dynamically generated page, or a page with dynamic and interactive elements (i.e. using JavaScript in the web browser), but not necessarily one that was also dynamically generated by a web application.

HTTP

The protocol—akin to an envelope—used to send instructions between one place on the network, and another. HTTP is the protocol of the Web, and is thus used by a web browser (on a client computer) to send a request to a web server application (on a server computer).

Request

The letter inside the HTTP envelope, is a request. It contains the instructions sent from the visitor's browser, asking the server for a page at a particular address, and if submitting (posting) a form, the contents of each field.

Address

All web sites and their pages have addresses. These comprise a domain name (e.g. example.com — representing a server), and an optional ‘path’ (e.g. /mystuff — representing a resource on that server, such as a folder or file). Together these form the address example.com/mystuff yet this address could be for somewhere other than the Web, so to identify it as a web address it can be further combined (prefixed) with the Web's protocol, to form a URL, becoming http://example.com/mystuff.

Although a full URL properly represents a web address, some web sites use a server with a domain name starting www. (such as www.example.com) and in this case the http:// prefix is somewhat redundant as it is clear that the domain is a ‘world wide web’ (thus HTTP) address. Further, because the web is the most popular part of the Internet, it is almost given that any address without an identifying prefix (such as example.com/mystuff or just example.com) is probably a web address and not, for example, an FTP address.

Web server

This application is the frontend of a server which accepts and responds to HTTP requests (often many simultaneously). With static websites, content is hosted (served from disk) by the web server itself, however with dynamically generated sites, the pages are generated by a web application through a backend of which a server may have one, or many for the same or different web applications. Some web servers may integrate the backend, whilst others may use separate backend application server programs or even separate server computers.

Web application

Software (a set of instructions) that dynamically generates pages, such that they appear different for every visitor, or every time they are accessed, by incorporating values from a database (a data storage application) into the page according to various criteria defined by the application developer. Such applications are built using a programming framework. [Moonstalk is used to build web applications.]

Framework

The integrated components of a programming language and libraries of useful software commands. This aids performing specific tasks, and in the development of web applications, which are run by a backend. [Moonstalk provides a framework.]

Backend

A server application that understands and interprets the language of a web application (e.g. PHP, Ruby, C#, Lua), to generate its pages on-demand when the web server forwards requests to it. [Moonstalk provides a backend.]

FastCGI

Another protocol, used to forward HTTP requests from the web server application, onto the backend application. In effect the request sent in a HTTP envelope between two different computers (client and server) is taken out, and put in a FastCGI envelope to be sent between the two different programs (frontend web server and backend page server—typically on the same computer).

Hosting

The service and functionality of delivering something such as a web page from somewhere, such as a web server, to someone, such as a visitor—thus web hosting. Both a server or service provider offering hosting are called a host. [Moonstalk configures and provides hosting.]

Server node

This is a host, that is either a dedicated (physical), virtualised (VPS/cloud), or a shared server (shared hosting) that runs the operating system (e.g. OS X or Linux) on which a web server application is installed (a web server). The server operating system (OS) provides bottom-layer functionality such as networking and storage. A server node is managed by an operator, or service provider, and provides hosting services to multiple site owners.

Moonstalk terminology

Lua

This is a programming language and a runtime (application) for interpreting software code written in its language, so that it can be run (executed) on a computer. [Moonstalk and its hosted web applications use Lua.]

Pages

HTML ‘view’ (layout) files, containing database field markers or server processing tags, and optional counterpart Lua ‘controller’ (logic) files. When we refer to 'pages' we may be referring to either or both of these components.

Sites

Folders of pages and images, etc.. A site’s pages are specific to one or more domain names. Sites may be managed by individual site owners.

Applications

As with sites, but comprising additional Lua files for functions. Applications may be accessed across multiple sites. Applications are installed by the server operator and not site owners.

‘Scribe’ Backend

The FastCGI server program that receives requests from the web server, and returns pages from a site after generating them, and typically by querying an application, database or folder for their content. Multiple scribe processes ('backends') run simultaneously on a single server node, and the web server queues requests, passing them to the next available backend.

‘Teller’ Database

Moonstalk's database system is a server program that handles requests from scribe servers to fetch or save data. The teller uses native Lua as both the protocol and query language (not SQL), and does not use a defined schema. The teller also provides persistence (automatically saves data) and replication (synchronisation with other nodes).

‘Manager’ Application

This is an included web application, available by default on all your sites, that enables per-site access to a page and content management system (CMS).

‘Runner’ Utility

This is a command-line launcher program that provides the functionality to start, stop or restart the Moonstalk components, including the web scribe.

‘Watchdog’ Utility

This application keeps an eye on Moonstalk's applications and can tell the runner to restart them and notify someone if problems are detected.

Libraries

Moonstalk relies on a variety of shared third-party software for specific functions. Applications may in turn utilise these, or their own. In Lua libraries are referred to as 'modules'.