The always-on image

An always-on computer is XataWorks running with no window, in a container. Whether you run it yourself or a hosting service runs it for you, it is the same image: ghcr.io/webliteca/xataworks. This page lists what it needs, the settings it reads, which tag to use, how it reports its health and where each version’s notes are.

What it needs

• Linux on an Intel or AMD (amd64) or ARM (arm64) processor. One image covers both; your container runtime picks the right one.
• Memory: at least 512 MB for one small BBS, and 2 GB to serve comfortably. XataWorks uses at most half of the container’s memory for itself and leaves the rest for web connections and databases. Its status card warns you when it is short of memory.
• One processor core is enough for a computer that mostly waits for visitors.
• No ports. It only dials out, so nothing needs opening on a router or a firewall.

The data folder

Everything the computer keeps — its link to your account, its BBSes, creations, databases and documents — is in one folder inside the container, /data. Give it a volume of its own and keep that volume when you update: a new image with the same volume is the same computer. Run one container per volume; two copies of the same data are the same computer twice.

If you mount a folder of your own rather than a named volume, give it to the user the image runs as first: sudo chown -R 10001:10001 /path/to/folder.

Settings

Both settings are optional environment variables.

AAF_PAIRING_TICKET

A pairing ticket, beginning cpt_. Choose Add a hosted always-on computer… in XataWorks on your desktop (Preferences → Web access) or in My computers on the web, copy the ticket, and paste it here. When the computer starts it links itself to your account — no code to type, no log to read. A ticket works once, within 60 minutes of being made, and you can cancel the ones you don’t use under Unused tickets. If a ticket can’t be used, the computer says why in its log and shows a pairing code instead, which you type with Add an always-on computer….

AAF_COMPUTER_NAME

The name your computers list shows, 1 to 80 characters. Without it, the computer uses its host name.

The image sets one more, AAF_HEALTH_FILE, for its health check. Leave it as it is.

Which tag to use

Tag	What it is
stable	The latest release. It changes only when a new version is released. latest is the same image.
1.42	The latest release in that line, for example 1.42.3 — fixes, without moving to 1.43.
1.42.0	Exactly that version, forever. Pin it to decide yourself when to update.
beta	The latest pre-release, for trying the next version early. A pre-release never moves stable.

Every tag can be pulled without signing in. The computer never updates itself: to update, pull the newer image and start a new container with the same volume.

Health

The image has a health check built in, so docker ps, and any hosting service that reads container health, can tell whether it is working:

• Healthy once XataWorks is up and has reached the XataWorks account service — usually within a minute of starting. A computer that is waiting for you to type its pairing code is healthy.
• Unhealthy about two minutes after it stops responding. Restart it; with --restart unless-stopped Docker does not restart an unhealthy container by itself, but most hosting services do.

If the account service can’t be reached when it starts, the computer says so in its log and stays unhealthy until it can.

Release notes

Every version has notes in two parts: what changed for owners, and anything a host must change to run it — a new setting or a new minimum. They are published with the release, with the version’s tags, on the same release page as that version’s downloads, in the webliteca/xataworks-releases repository on GitHub.

Running it

With Docker, in one line:

docker run -d --name xataworks --restart unless-stopped -v xataworks-data:/data -e AAF_PAIRING_TICKET=cpt_… ghcr.io/webliteca/xataworks:stable

For a computer you keep at home, with the steps for a Raspberry Pi and a Synology NAS, see An always-on computer at home.