massix86/gleeter repository overview

Run Gleeter in serve mode to serve XKCD comics over HTTP.

This Docker image is specifically designed for running Gleeter in serve mode. It provides an HTTP server that allows you to access XKCD comics via various endpoints:

• /: Serves the latest comic.
• /latest: Serves the latest comic (same as /).
• /random: Serves a random comic.
• /id/<number>: Serves the comic with the specified ID. Replace <number> with the desired comic ID.

You can customize the base path for these endpoints by passing the <base_path> argument to the serve command. For example:

docker run --rm massix86/gleeter serve 8080 /comics

This will start the server on port 8080 and serve the comics under the /comics path. The endpoints will then be:

• /comics/
• /comics/latest
• /comics/random
• /comics/id/<number>

The server also supports receiving the terminal size via HTTP headers. Send X-TERMINAL-COLUMNS and X-TERMINAL-ROWS headers to specify the terminal size and have the comic properly formatted. You need to send both headers for resizing to work.

Configuration File Support:

Serve mode honors aliases defined in a TOML configuration file. Create a config.toml file and mount it to /app/config.toml in the container. Example:

[[alias]]
name = "bobbytables"
type = "id"
id = 987

[[alias]]
name = "rnd"
type = "random"

[[alias]]
name = "l"
type = "latest"

With the above configuration, and the server running with a /comics base path, you'll also get the following endpoints:

• /comics/bobbytables (alias for /comics/id/987)
• /comics/rnd (alias for /comics/random)
• /comics/l (alias for /comics/latest)

Health Check:

A /health endpoint is available, returning a JSON structure with server status and performance information.

Prometheus Metrics:

Gleeter exposes Prometheus metrics at the /metrics endpoint.

You can configure the metrics endpoint using the following options in the config.toml file:

[metrics]
ignore_base_path = true  # Expose /metrics regardless of the base path
username = "metrics_user" # Enable basic authentication
password = "metrics_password"

When ignore_base_path is true, the metrics endpoint is always accessible at /metrics.

To protect the metrics endpoint, provide a username and password. Clients must then authenticate using HTTP Basic Auth to access the metrics.

See the project's README for further details and a complete list of available metrics: https://github.com/massix/gleeter⁠