Algernon

<!-- title: Algernon description: Web server with built-in support for Lua, Teal, Markdown, Pongo2, Amber, Sass, SCSS, GCSS, JSX, Bolt, PostgreSQL, SQLite, Redis, Valkey, MariaDB, MySQL, MSSQL, Tollbooth, Pie, Graceful, Permissions2, users and permissions, IPv6 keywords: web server, QUIC, lua, teal, markdown, pongo2, application server, http, http2, HTTP/2, go, golang, algernon, JSX, React, BoltDB, Bolt, PostgreSQL, SQLite, Redis, Valkey, MariaDB, MySQL, Three.js, ipv6 theme: material --> <!--<a href="https://github.com/xyproto/algernon"><img src="https://algernon.roboticoverlords.org/img/algernon_logo.png" style="margin-left: 2em"></a>-->

Web server with built-in support for QUIC, HTTP/2, Lua, Teal, Markdown, Pongo2, HyperApp, Amber, Sass(SCSS), GCSS, JSX, Ollama (LLMs), BoltDB (built-in, stores the database in a file, like SQLite), Redis, Valkey, PostgreSQL, SQLite, MariaDB, MySQL, MSSQL, IPv6, rate limiting, graceful shutdown, plugins, users and permissions.

All in one small self-contained executable.

Distro Packages

Quick installation

Requires Go 1.25 or later.

go install github.com/xyproto/algernon@latest

Or manually (development version):

git clone https://github.com/xyproto/algernon
cd algernon
go build -mod=vendor
./welcome.sh

Releases and pre-built images

See the release page for releases for a variety of platforms and architectures.

Getting Started

See TUTORIAL.md.

Docker

The Docker image is less than 12MB and can be tried out (on x86_64) with:

mkdir localhost
echo 'hi!' > localhost/index.md
docker run -it -p4000:4000 -v .:/srv/algernon xyproto/algernon

And then visiting http://localhost:4000 in a browser.

Technologies

Written in Go. Uses Bolt (built-in), MySQL, PostgreSQL, SQLite or Valkey/Redis (recommended) for the database backend, permissions2 for handling users and permissions, gopher-lua for interpreting and running Lua, optional Teal for type-safe Lua scripting, http2 for serving HTTP/2, QUIC for serving over QUIC, gomarkdown/markdown for Markdown rendering, amber for Amber templates, Pongo2 for Pongo2 templates, Sass(SCSS) and GCSS for CSS preprocessing. logrus is used for logging, goja-babel for converting from JSX to JavaScript, tollbooth for rate limiting, pie for plugins and graceful for graceful shutdowns.

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.
• QUIC ("HTTP over UDP", HTTP/3) can be enabled with a flag.
• /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 Lua code that is interpreted as a handler function for the current directory.
  • index.html is HTML that is outputted with the correct Content-Type.
  • index.md is Markdown code that is rendered as HTML.
  • index.txt is plain text that is outputted with the correct Content-Type.
  • index.pongo2, index.po2 or index.tmpl is Pongo2 code that is rendered as HTML.
  • index.amber is Amber code that is rendered as HTML.
  • index.hyper.js, index.hyper.jsx or index.happ is JSX+HyperApp code that is rendered as HTML.
  • index.tl is Teal code that is interpreted as a handler function for the current directory.
  • index.prompt is a content-type, an Ollama model, a blank line and a prompt, for generating content with LLMs.
  • data.lua is Lua code, where the functions and variables are made available for Pongo2, Amber and Markdown pages in the same directory.
  • If a single Lua script is given as a command line 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 GCSS code that is used as the style for all Pongo2, Amber and Markdown pages in the same directory.
• The following filename extensions are handled by Algernon:
  • Markdown: .md (rendered as HTML)
  • Pongo2: .po2, .pongo2 or .tpl (rendered as any text, typically HTML)
  • Amber: .amber (rendered as HTML)
  • Sass: .scss (rendered as CSS)
  • GCSS: .gcss (rendered as CSS)
  • JSX: .jsx (rendered as JavaScript/ECMAScript)
  • Lua: .lua (a script that provides its own output and content type)
  • Teal: .tl (same as .lua but with type safety)
  • HyperApp: .hyper.js or .hyper.jsx (rendered as HTML)
• 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 hard coded.
• UTF-8 is used whenever possible.
• The server can be configured by command line 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 (browsers may require HTTPS when using HTTP/2).
• Also supports QUIC and regular HTTP.
• Can use Lua scripts as handlers for HTTP requests.
• The Algernon executable is compiled to native and is reasonably fast.
• Works on Linux, macOS and 64-bit Windows.
• The Lua interpreter is compiled into the executable.
• The Teal typechecker is loaded into the Lua VM.
• Live editing/preview when using the auto-refresh feature.
• The use of Lua allows for short development cycles, where code is interpreted when the page is refreshed (or when the Lua file is modified, if using auto-refresh).
• 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, Pongo2, Amber, Sass(SCSS), 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 Sass, GCSS and data.lua). This only works on Linux and macOS, 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. This can be handy for viewing README.md files locally. Use -m to display it in a browser and only serve it once.
• Full multi-threading. 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).
• If cache compression is 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](https://golang.org/pkg/