LaTeXRender

What a licence includes

A licence is a key and a Docker Hub credential. There is no installer, no TeX to configure and no package list to curate — the images carry a TeX distribution built for this purpose, including the CodeCogs extensions.

The key is checked by the cgi service at startup and is what ties a deployment to an organisation. It is passed as an environment variable, which means it belongs in your orchestrator's secret store rather than in a file you commit.

Docker deployment

Deployment is one command against a Swarm. The images are private, so the registry credential has to travel with the deploy — that is what --with-registry-auth does, and leaving it off produces a stack whose tasks never start because no node can pull anything.

docker login
docker stack deploy --with-registry-auth --compose-file docker-cgi.yml eqnCopy

Check it came up, and that TeX answers:

docker stack services eqn
curl "http://localhost/png.image?x^2"Copy

Updating to a new release is the same command with a new tag in the file. Swarm rolls the replicas one at a time, so the service stays up throughout.

docker-cgi.yml

The file we deploy our own estate with, with the credentials removed. Six replicas of the renderer, at most two to a node, is a sensible starting point for a few hundred thousand equations a day; the cache in front of it means most requests never reach TeX at all.

version: "3.9"

services:
    cgi:
        image: willzyba/eqneditor-cgi:5.9.2.1
        deploy:
            mode: replicated
            replicas: 6
            placement:
                max_replicas_per_node: 2
            restart_policy:
                condition: any
                delay: 5s
                max_attempts: 5
                window: 120s
        volumes:
            - ./eq:/var/www/eq              # Cached equation files
            - ./usr:/var/www/usr            # Usage logs
            - ./log:/var/www/log            # System logs
            - ./settings:/var/www/settings  # Settings
            - ./file:/var/www/file          # Permanent file storage
            - type: tmpfs
              target: /tmp/ramdisk          # TeX scratch space
        tty: true
        environment:
            - EQN_RENDER_URL=https://equations.example.com   # Where this service is reachable
            - EQN_PARENT_DOMAIN=example.com                  # The site the equations are for
            - EQN_LICENCE=<your licence key>
            - EQN_POD_NAME=Docker-{{.Task.ID}}
            - EQN_ADMIN_PASSWORD=<choose one>
        ports:
            - 80:80
        healthcheck:
            test: wget -qO - http://localhost/health || exit 1
            interval: 60s
            timeout: 15s
            retries: 3
            start_period: 15s

    html:
        image: willzyba/eqneditor-html:5.8.1.44
        deploy:
            mode: replicated
            replicas: 2
            placement:
                max_replicas_per_node: 1
            restart_policy:
                condition: any
                delay: 5s
                max_attempts: 5
                window: 500s
        volumes:
            - ./eq:/var/www/html/eq
            - ./log:/var/www/log
        tty: true
        environment:
            - EQN_RENDER_URL=https://equations.example.com
            - EQN_RENDER_SERVICE_URL=http://cgi
        ports:
            - 5000:80

    clean:
        image: willzyba/eqneditor-clean:5.8.1.44
        deploy:
            mode: global
            restart_policy:
                delay: 30m
        volumes:
            - ./eq:/var/www/eq
            - ./log:/var/www/logCopy

Configuration

Volumes

./eq is the equation cache, and is the reason the service is fast. An equation that has been rendered once is served as a file thereafter. It is shared between the cgi, html and clean services, so on a multi-node Swarm it needs to be shared storage rather than a per-node bind mount.

./settings holds configuration that survives a redeploy. Back it up.

./usr and ./log are usage records and system logs.

/tmp/ramdisk is deliberately tmpfs. TeX writes a considerable amount of scratch per equation, all of it disposable, and keeping it off the disk is worth a measurable amount of latency.

Scaling

Rendering is CPU-bound and each request is independent, so the renderer scales by replica count and nothing else. max_replicas_per_node keeps one busy node from taking the whole service down with it. The clean service runs global — one per node — because each node has its own disk to keep from filling.

More

The URL format, output types, sizes, colours and the JSON interface are all on the API page. To point the editor or a plugin at your own deployment instead of ours, set its renderUrl to your EQN_RENDER_URL.

For licensing, talk to us.