About Algernon

Algernon is written in Go and uses Bolt (built-in), MySQL or Redis (recommended) for the database backend, permissions2 for handling users and permissions, gopher-lua for interpreting and running Lua, http2 for serving HTTP/2, blackfriday for Markdown rendering, amber for Amber templates and GCSS for CSS preprocessing. logrus is used for logging, risotto for converting from JSX to JavaScript, tollbooth for rate limiting, pie for plugins and graceful for graceful shutdowns.

There is built-in support for:

  • The Lua programming language and an API for creating web applications.
  • Handling users and permissions. Password are stored as bcrypt hashes.
  • Three different database backends: Redis, MySQL or the built-in Bolt database.
  • Rate limiting, preventing a single user from overloading the server.
  • Caching, where the data is stored as gzipped data, ready to push out to the browser without compressing it per request.
  • HTTP/2, a modern protocol for the web, backed by Google and other companies, supported by Chrome and Firefox.
  • Instantly refresh a served page when a file changes on the server, automatically, using Streamed Events, JavaScript and file system notifications.
  • HTTPS, for secure connections.

Design decisions

  • HTTP/2 over SSL/TLS (https) is used by default, if a certificate and key is given.
    • If not, regular HTTP is used.
  • /data and /repos have user permissions, /admin has admin permissions and / is public, by default. This is configurable.
  • The following filenames are special, in prioritized order:
    • index.lua is interpreted as a handler function for the current directory.
    • index.md is rendered as HTML.
    • index.html is outputted as it is, with the correct Content-Type.
    • index.txt is outputted as it is, with the correct Content-Type.
    • index.amber is rendered as HTML.
    • data.lua is interpreted as Lua code, where the functions and variables are made available for Amber and Markdown pages in the same directory.
    • If a single Lua script is given as a commandline argument, it will be used as a standalone server. It can be used for setting up handlers or serving files and directories for specific URL prefixes.
    • style.gcss is used as the style for Amber and Markdown pages in the same directory.
  • The following filename extensions are handled by Algernon:
    • .md is interpreted as Markdown and rendered as a HTML page.
    • .amber is interpreted as Amber and rendered as a HTML page.
    • .gcss is interpreted as GCSS and rendered as a CSS file.
    • .jsx is interpreted as JSX and rendered as a JavaScript file.
    • .lua is interpreted as a Lua script that provides its own output and content type.
  • Other files are given a mimetype based on the extension.
  • Directories without an index file are shown as a directory listing, where the design is hardcoded.
  • UTF-8 is used whenever possible.
  • The server can be configured by commandline flags or with a lua script, but no configuration should be needed for getting started.

Features and limitations

  • Supports HTTP/2, with or without HTTPS.
  • Supports regular HTTP.
  • Can use Lua scripts as handlers for HTTP requests.
  • The server is compiled to native.
  • Works on Linux, OS X and 64-bit Windows.
  • Reasonably fast.
  • The Lua interpreter is built-in.
  • The use of Lua allows for short development cycles, where code is interpreted when the page is refreshed (there is an auto-refresh feature).
  • Self-contained Algernon applications can be zipped into an archive (ending with .zip or .alg) and be loaded at start.
  • Built-in support for Markdown, Amber, GCSS and JSX.
  • Redis is used for the database backend, by default.
  • Algernon will fall back to the built-in Bolt database if no Redis server is available.
  • The HTML title for a rendered Markdown page can be provided by the first line specifying the title, like this: title: Title goes here. This is a subset of MultiMarkdown.
  • No file converters needs to run in the background (like for SASS). Files are converted on the fly.
  • If -autorefresh is enabled, the browser will automatically refresh pages when the source files are changed. Works for Markdown, Lua error pages and Amber (including GCSS and data.lua). This only works on Linux and OS X, for now. If listening for changes on too many files, the OS limit for the number of open files may be reached.
  • Includes an interactive REPL.
  • If only given a Markdown filename as the first argument, it will be served on port 3000, without using any database, as regular HTTP. Handy for viewing README.md files locally.
  • Full multithreading. All available CPUs will be used.
  • Supports rate limiting, by using tollbooth.
  • The help command is available at the Lua REPL, for a quick overview of the available Lua functions.
  • Can load plugins written in any language. Plugins must offer the Lua.Code and Lua.Help functions and talk JSON-RPC over stderr+stdin. See pie for more information. Sample plugins for Go and Python are in the plugins directory.
  • Thread-safe file caching is built-in, with several available cache modes (for only caching images, for example).
  • Can read from and save to JSON documents. Supports simple JSON path expressions (like a simple version of XPath, but for JSON).
  • With cache compression enabled, files that are stored in the cache can be sent directly from the cache to the client, without decompressing.
  • Files that are sent to the client are compressed with gzip, unless they are under 4096 bytes.