How-to

Install a slowapp

Add a published slowapp to a hub, put its cards on a screen, and check that it runs.

You need a running hub with shell access to its machine (on a Slowboard 1085, SSH to the board), and the app’s release: its slowapp.toml and the pinned image = "…@sha256:…" line from its release notes. The examples install Reminders.

Run slowhub commands as the hub’s user; the slowhub reference has the full command line.

1. Put the manifest on the hub

Copy the app’s slowapp.toml to /opt/slowboard/apps/<id>/, for example /opt/slowboard/apps/reminders/slowapp.toml.

2. Pull the image

The hub runs images that are already on its machine. Pull the release by digest as the hub’s user (epaper on a Slowboard 1085):

u=$(id -u epaper)
runuser -u epaper -- env XDG_RUNTIME_DIR=/run/user/$u DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$u/bus \
  podman pull ghcr.io/mike-anderson/slowapp-reminders@sha256:…

3. Add the app to the hub

Add an [[app]] entry to /etc/slowhub/slowhub.toml:

[[app]]
id = "reminders"
runner = "podman"
manifest = "/opt/slowboard/apps/reminders/slowapp.toml"
image = "ghcr.io/mike-anderson/slowapp-reminders@sha256:…"

The id must match the manifest’s [app] id. The image is always pinned by digest, so a release can’t change under you. Then restart slowhub:

systemctl --user -M epaper@ restart slowhub

4. Approve its grants and set its secrets

TODO(owner): approving an app’s grants and setting its secrets are planned for the hub’s web interface. Say what someone does today, or confirm the docs should describe the planned steps.

An app that needs a secret it doesn’t have stops with “needs config” until the secret is set.

5. Put its cards on the screen

Add the app’s feed to a slot in the layout, as <app>/<feed>. For an app that asks questions, also list the feed as a question source:

"prompt_sources": ["reminders/prompts"]

Layout and preferences shows how to change the layout.

6. Check it ran

slowhub update        # render everything now, then refresh the screen
slowhub runs 5        # the last five runs and their outcomes

A successful render has the outcome new. To check that the image works on this hub without network or secrets, render the app’s own examples:

slowhub run reminders render --fixture

A slot whose new feed has no cards yet shows “waiting” in its strip. After a layout change, slowd keeps the old layout until every slot has cards, for up to 15 minutes.

If something is wrong, see Troubleshooting.