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.
Please be aware that Moonstalk is not suited to the following scenarios. See our Pivotal Tracker project for tasks and fixes in upcoming iterations.
You should be able to run Moonstalk on pretty much any Linux or UNIX-based computer.
Moonstalk is not 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).
Disable the openresty and tarantool services if installed and enabled. These are not used with moonstalk therefore you must stop the instance already started and prevent it from starting automatically.
openresty (packages Nginx with some extras) is the default web and application server. tarantool is an optional database and Lua application server (skip this if you'll be using another, or the included low-traffic datastore). lua5.1 is the language runtime that Moonstalk uses. libuv is a library for handling inter-process communications. LuaRocks is an optional package manager for Lua modules. git 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.
The ./elevator 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.
Lua must be available as a binary named lua5.1, create a symlink if it has any other name, or simply invoke the elevator from its binary directly lua elevator.
If you prefer you may install modules manually, providing they can be found in $LUA_PATH.
If you're setting up a production server, be sure to edit data/configuration/Host.lua before proceeding. Or simply: ./elevator hostname=server.example.com logging=1
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.
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.
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.
If you're working with multiple colleagues, you can use the Git distributed concurrent versioning system (dCVS), as used by Moonstalk itself for installation.
…you'll also need a diff utility:
…and somewhere to store your Mercurial repository (a share point):
Moonstalk includes a simple CMS system named Manager, you'll need an administrator login to use it, simply 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.
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.
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.
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.
127.0.0.1 which is your computer's local address, allowing only you to access it.
Remember 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.
After defining a site, you can start Moonstalk. The following command will start all the web/pages servers (and db if configured) in development mode which disables Moonstalk's page caching — allowing you to see changes as you refresh a page in your browser after changing them.
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.
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>Moonstalk's version is: ?(moonstalk.deployment.version)</p>
?( wibble ) markup is called an expression tag (or «placeholder» / write macro). When a page containing this is requested, Moonstalk evaluates the variable or expression inside the tag (e.g. wibble) and replaces the tag with the result.
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. This uses a Moonstalk table, surprise surprise(!) named form to access user submitted values.
<h2>Hello ?( request.form.name or "have we met?" )</h2> <p>What’s your name?</p> <form method="post"> <input type="text" name="name"> <input type="submit"> </form>
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>
<? ?> markup is called a server processing tag. Inside this you can run any valid Lua code.
scribe.Insert("content") is a function you can use in templates that indicates where in the template to put the content from the requested view, in this case hello.html. You can also declare other sections (than content) in views, to later insert elsewhere.
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 request.form.myinput then save ( mydata.isaved, request.form.myinput ) end
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 request.form.myinput then save ( mydata.isaved, request.form.myinput ) log.Append( "=======UPDATE:" .. request.form.myinput ) else log.Append "=======FETCH" end
Linux
- tail -f temporary/moonstalk.log
OS X
- double-click the temporary/moonstalk.log file
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.
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.
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).
A collection of pages that are accessed via a web browser application (e.g. 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.
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).
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 (which can be better considered a parcel).
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.
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.
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.]
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.]
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 operates in backends.]
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).
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.]
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.
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.]
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.
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.
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.
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.
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).
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).
This is an interactive command-line launcher program that provides the functionality to start, stop or restart the Moonstalk components.
A command-line program enabling you to directly interact with each Moonstalk environment in its application servers (on the same server), such as the web backends and database.
This application keeps an eye on Moonstalk's applications and can tell the elevator to restart them and notify someone if problems are detected.
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'.