Algernon

• In the Azure Portal, choose Create a resource and search the Marketplace for Algernon on Ubuntu 24.04 LTS by SecureAnyCloud.
• Select the offer and choose Create.
• On the Basics tab, pick your subscription, resource group and region, set the VM name, and choose size Standard_B2s.
• Leave the authentication type as SSH public key and the username as azureuser.
• Under Inbound port rules, allow SSH (22), HTTP (80) and HTTPS (443).
• Select Review + create, then Create. The VM is ready in about a minute, and first boot generates this VM's TLS certificate.

Create a resource group, accept the Marketplace terms and create the VM:

az group create --name algernon-rg --location eastus
az vm image terms accept --urn sac1647283583153:algernon:default:latest
az vm create \
  --resource-group algernon-rg \
  --name algernon-vm \
  --image sac1647283583153:algernon:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard
# the public address of the new VM
az vm show --resource-group algernon-rg --name algernon-vm \
  --show-details --query publicIps --output tsv

Then open the ports your site needs.

az network nsg rule create --resource-group algernon-rg \
  --nsg-name algernon-vmNSG --name allow-http \
  --priority 1010 --destination-port-ranges 80 443 \
  --protocol Tcp --access Allow --direction Inbound

Connect over SSH as azureuser:

ssh azureuser@<public-ip>

Confirm that the service came up and check which upstream artifact this image shipped:

algernon --version systemctl is-active algernon.service cat /opt/algernon/VERSION

Expected output:

Algernon 1.17.11 active product=Algernon version=1.17.11 upstream=https://github.com/xyproto/algernon release=https://github.com/xyproto/algernon/releases/download/v1.17.11/algernon-1.17.11-linux_x86_64_static.tar.xz tarball_sha256=73075b76ccbc5bf9d383e95ca9987cd66a1bf46f37dfeaa00ec0ad5714871abf binary_sha256=cd81e9884f8ac9797e32129b7f903421292578eb93ef19dc71007c7efa935a3e licence=BSD-3-Clause (verbatim text at /opt/algernon/LICENSE)

The appliance listens on three ports only. List them and their owners:

sudo ss -lntp | grep -E ':(22|80|443)\s'

Ports 80 and 443 belong to algernon. There is no monitor port, no admin console, no debug endpoint and no database listener, because the datastore is an embedded file rather than a separate daemon.

Open http://<ALGERNON_HOST>/ in a browser. You land on index.lua, executed on the server for that request. Reload the page and the generated timestamp changes.

The shipped selftest checks the whole thing in one command:

sudo /usr/local/sbin/algernon-selftest

The selftest exits non-zero and says why if anything is wrong. On a healthy VM it reports that:

• Markdown rendered into real HTML elements
• Lua executed per request
• The same site is served over TLS with HTTP/2
• No REPL, debug or scripting surface is exposed

Markdown is rendered, not served verbatim. /srv/algernon/welcome.md is an ordinary Markdown file. Request it over HTTP and you get HTML:

grep -m1 '^## ' /srv/algernon/welcome.md curl -s http://127.0.0.1/welcome.md | grep -oE '<h2[^>]*>[^<]*</h2>' | head -1 curl -s http://127.0.0.1/welcome.md | grep -oE '<td>[^<]*</td>' | head -2

The heading arrives as an <h2> element and the pipe table arrives as <td> cells. Neither tag exists anywhere in the source file.

Lua executes on every request. /srv/algernon/status.lua sums the numbers 1 to 100 in a loop and multiplies any ?n= parameter by six, so the answers cannot be sitting in a file waiting to be served:

curl -s http://127.0.0.1/status.lua
curl -s 'http://127.0.0.1/status.lua?n=7' | grep '^echo:'
curl -s 'http://127.0.0.1/status.lua?n=9' | grep '^echo:'

Expected output:

SAC_ALGERNON_LUA_OK:5050 echo:0 path:/status.lua method:GET tick:12.345678 server:Algernon on Ubuntu 24.04 LTS by sac echo:42 echo:54

The tick value changes on every request, even for an identical URL. This shows that the response is computed rather than replayed from a cache.

Algernon terminates TLS itself. The same site is served on port 443 with HTTP/2 negotiated by ALPN, using a certificate generated on this VM at first boot. Verify it:

curl -sk https://127.0.0.1/status.lua | head -1
curl -sk --http2 -o /dev/null -w 'negotiated HTTP/%{http_version}\n' https://127.0.0.1/ echo | openssl s_client -connect 127.0.0.1:443 2>/dev/null | openssl x509 -noout -subject -dates

The certificate is self-signed, so a browser warns until you install your own. It is unique to this VM: no certificate and no private key ship in the image, so no two customers, and no two of your own VMs, share TLS key material. The private key lives at /etc/algernon/tls/key.pem as 0640 root:algernon.

Every response also carries the standard protective headers plus a content security policy:

curl -sI http://127.0.0.1/ | grep -iE '^(server|x-content-type-options|x-frame-options|x-xss-protection|content-security-policy):'

First boot writes a summary of this VM's own endpoints and paths, readable only by root. Read it:

sudo cat /root/algernon-endpoints.txt

The file records the public URL, the document root, the datastore path, the log paths, the certificate fingerprint and the selftest command. Algernon has no login and no password, so the file contains no credential. It exists so you always know where everything lives.

The document root is /srv/algernon. Add files as root and they are served immediately, with no build step and no restart:

sudo tee /srv/algernon/example-page.md >/dev/null <<'PAGE'
# My first page This file was written as plain Markdown and is being rendered on request. - Markdown becomes a themed HTML page - A `.lua` file runs server side and writes its own response - Anything else is served as an ordinary static file PAGE curl -s http://127.0.0.1/example-page.md | grep -oE '<h1[^>]*>[^<]*</h1>'
sudo rm -f /srv/algernon/example-page.md

The file extension decides how Algernon treats a file:

• .md, .markdown: rendered as Markdown into a themed HTML page
• .lua, .tl: executed server-side, writes its own response
• .amber, .po2, .pongo2, .tmpl: rendered as a template
• .gcss, .scss: rendered to CSS
• .jsx, .tsx, .ts: transpiled for the browser
• Anything else: served as a static file

Index files are resolved in this order, so an index.lua wins over an index.html, which wins over an index.md.

The shipped default site consists of three files: index.lua, welcome.md and status.lua. List them, and delete them once your own site is in place:

ls -la /srv/algernon/

Why root owns the document root, not the service account. Algernon executes any .lua file it finds in the document root. It also executes a serverconf.lua there automatically as server configuration, if one exists.

If the account Algernon runs as could write into that directory, any bug that let an attacker write a file would become remote code execution. So the tree is root:root, and the systemd unit also mounts the whole filesystem read-only for the service, except the datastore and log directories. Use sudo to publish, and do not chown the tree to the service account.

Replace the self-signed pair with a certificate for your own domain, keeping the same paths and ownership:

sudo install -o root -g algernon -m 0644 \
  /etc/letsencrypt/live/<your-domain>/fullchain.pem /etc/algernon/tls/cert.pem
sudo install -o root -g algernon -m 0640 \
  /etc/letsencrypt/live/<your-domain>/privkey.pem /etc/algernon/tls/key.pem
sudo systemctl restart algernon

Algernon can also obtain and renew certificates itself using Let's Encrypt. This suits a VM that already has a public DNS name pointed at it. Add --letsencrypt --domain to the ExecStart line in the unit and remove the --cert and --key flags.

Test against the staging CA first with --testcert, so a misconfiguration does not use up your rate limit.

All configuration is on the ExecStart line of the systemd unit, so there is one place to look. Print it:

systemctl cat algernon.service | grep -A20 ExecStart

This image sets the following flags:

• --dir=/srv/algernon: the document root
• --http-addr=:80 / --https-addr=:443: serve both, with no forced redirect
• --cert / --key: the per-instance certificate generated at first boot
• --boltdb=/var/lib/algernon/algernon.db: the embedded datastore, so there is no database daemon and no extra listener
• --cache=prod: cache static files and rendered Markdown, never cache Lua
• --limit=200: requests per second per client
• --noninteractive: no Lua REPL, and debug mode forced off
• --stricter: adds the content security policy
• --hide-dotfiles: dotfiles are neither listed nor served
• --servername=Algernon: identifies the product without publishing the exact build
• --accesslog / --log: request log and server log under /var/log/algernon

To change a flag, edit the unit and reload:

$
sudo systemctl edit --full algernon.service $
sudo systemctl daemon-reload $
sudo systemctl restart algernon

Two flags are useful while you author content. --cache=off makes Algernon re-read every file from disk on each request, which is what you want while editing. --autorefresh injects a small script that reloads the browser when a file changes.

Both are development conveniences. Leave them off in production, and note that --autorefresh opens an additional event stream port.

Flags this image deliberately does not set. --lua starts an interactive Lua prompt instead of serving. --debug renders failing Lua source, including file paths, straight into the HTTP response. --dev turns on debug mode and raises the rate limit. --nolimit removes rate limiting entirely.

None of these belong on an internet-facing VM, and the selftest checks that none of them is present on the running process.

Read the access log, the server log and the journal:

sudo tail -5 /var/log/algernon/access.log
sudo tail -5 /var/log/algernon/server.log
sudo journalctl -u algernon.service -n 20 --no-pager

The access log is Combined Log Format, so anything that reads Apache or nginx logs will read it. The server log is JSON, one object per line.

Note that Algernon does not always exit when something goes wrong. If it cannot read its TLS certificate, for example, it logs a single error, drops the HTTPS listener and carries on serving plain HTTP. systemd still reports active (running) and nothing restarts. When something looks wrong, read server.log instead of trusting the unit state:

sudo grep -c '"level":"error"' /var/log/algernon/server.log || echo 0