Algernon Web Server

Algernon includes MathJax assets for mathematical typesetting. The engine uses tex-mml-chtml.js (licensed under Apache 2) and tex-svg.js for rendering equations.

Note: The current version of tex-svg.js was fetched from the jsDelivr CDN (version 3.2.2).

Algernon is a self-contained web server written in Go that supports multiple protocols (HTTP, HTTP/2, HTTP/3/QUIC) and a wide array of templating and scripting languages.

Key capabilities include:

• Scripting: Built-in Lua and Teal support.
• Templating/Frontend: Markdown, Pongo2, Amber, Sass/SCSS, GCSS, JSX, and TypeScript (React 19).
• Databases: Built-in BoltDB (file-based), with support for Redis/Valkey, PostgreSQL, SQLite, MariaDB, MySQL, and MSSQL.
• Advanced Features: Rate limiting, graceful shutdown, user permissions, and plugin support.

After generating a Dockerfile with alg2docker, follow these steps to build and run the container:

1. Build the image:

   docker build -t <image_name> .

2. Run the container with HTTPS support: To serve the application over HTTPS, you must mount your local SSL certificates (cert.pem and key.pem) into the container at /etc/algernon using a volume.

   Ensure your certificates are located in $PWD/config before running:

   docker run -v "$PWD/config":/etc/algernon --publish 80:80 --publish 443:443 --rm <image_name>

When using Moonscript-compiled Lua files with Algernon, the behavior depends on how the Lua file is served:

1. Server Configuration Mode: If hello.lua (compiled from hello.moon) is served as a server configuration script, it sets up a simple handle.
2. Regular Handler Mode: If index.lua (compiled from index.moon) is served as a regular Algernon handler, it functions as a standard request handler.

Note that different Lua functions are available depending on which of these two modes is active.

You can run a lightweight Algernon instance using Docker. This example creates a local directory, adds a Markdown file, and mounts it to the container to serve it on port 4000.

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

To serve a directory as a static file server, create an index.lua file within that directory. Algernon will treat the directory as the root and use index.lua as the default handler for the directory path.

To serve the current directory:

# Create index.lua with content
echo 'print("the light")' > index.lua

# Run Algernon on the current directory
algernon .

You can install Algernon using go install if you have Go 1.26 or later installed. Alternatively, you can build it manually from the source code.

go install github.com/xyproto/algernon@latest

Algernon includes an auto-refresh feature that watches files for changes and uses Server-Sent Events (SSE) to trigger updates. It works by injecting a small amount of JavaScript into the served pages.

To enable auto-refresh, you must use the -a flag. It is often used in conjunction with development mode (-e).

Example command to serve the current directory with auto-refresh, development mode, and no security headers:

algernon -a -e --no-headers .

To quickly run Algernon in development mode, build and run the container using the provided helper scripts. After running, the service will be available at http://localhost:3000.

./build.sh dev
./run.sh dev

Algernon defaults to React 19. To select a different major version (if supported by the build), place a comment at the very top of your index.jsx or index.tsx file.

// React: 19