readerboard 0.1.2__tar.gz → 0.1.3__tar.gz

{readerboard-0.1.2/readerboard.egg-info → readerboard-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.1.2
+Version: 0.1.3
 Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
 Author: mjaksn
 License-Expression: MIT
@@ -27,7 +27,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi<0.142,>=0.141.1
-Requires-Dist: uvicorn[standard]<0.53,>=0.52.1
+Requires-Dist: uvicorn<0.53,>=0.52.1
 Requires-Dist: pydantic<3,>=2.13.4
 Requires-Dist: pydantic-settings<3,>=2.15.0
 Requires-Dist: pyserial<4,>=3.5
@@ -45,6 +45,8 @@ Dynamic: license-file
 [![CI](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml)
 [![Release](https://github.com/mjaksn/readerboard/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/release.yml)
 [![PyPI](https://img.shields.io/pypi/v/readerboard)](https://pypi.org/project/readerboard/)
+[![GHCR](https://img.shields.io/badge/ghcr.io-readerboard-blue)](https://github.com/mjaksn/readerboard/pkgs/container/readerboard)
+[![Docker Hub](https://img.shields.io/docker/v/mjaksn/readerboard?label=docker%20hub&sort=semver)](https://hub.docker.com/r/mjaksn/readerboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/readerboard/blob/main/LICENSE)
 
 An HTTP service that drives a BetaBrite Classic sign, either through a serial cable or
@@ -78,13 +80,14 @@ until it is released, after which the rotation resumes.
 - Python 3.11 or newer.
 - A BetaBrite Classic, reachable either at a serial device such as `/dev/ttyUSB0` or over
   the network through an Ethernet to RS-232 adapter at `socket://host:port`.
-- For the installer, a machine running systemd. The service itself runs anywhere Python
-  does; only `scripts/install.sh` is Linux specific.
+- Either a machine running systemd, for `scripts/install.sh`, or a container runtime, for
+  the published image. The service itself runs anywhere Python does; only the installer
+  is Linux specific.
 
 ## Try it without a sign
 
 `loop://` is pyserial's loopback, so the service will start and serve its API with
-nothing attached.
+nothing attached. From a checkout:
 
 ```
 pip install -e ".[dev]"
@@ -93,10 +96,22 @@ READERBOARD_SERIAL_URL=loop:// READERBOARD_API_KEY=dev-key \
     python -m readerboard
 ```
 
+Or without one:
+
+```
+docker run --rm -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=loop:// -e READERBOARD_API_KEY=dev-key \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
 Then open <http://127.0.0.1:5001/docs>.
 
 ## Installing it properly
 
+Two ways, which do the same job. Pick whichever suits the machine.
+
+### With systemd
+
 ```
 sudo scripts/install.sh --serial-url socket://192.168.2.51:4001
 ```
@@ -110,6 +125,40 @@ again after pulling a new version: your config file and key are left alone.
 your registered messages, so reinstalling puts the sign back as it was. Add `--purge` to
 remove those too.
 
+### With Docker
+
+The image is published to both registries on every release, for `linux/amd64`,
+`linux/arm64` and `linux/arm/v7`, so a Pi pulls the same tag an x86 server does.
+
+```
+docker run -d --name readerboard --restart unless-stopped -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=socket://192.168.2.51:4001 \
+    -e READERBOARD_API_KEY=YOUR-KEY \
+    -v readerboard-state:/var/lib/readerboard \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
+`packaging/docker-compose.yml` is the same thing as a Compose file, with the settings
+worth knowing about written out beside it.
+
+The volume is what matters here. The registered messages are persisted to
+`/var/lib/readerboard`, and without it the sign comes back empty after a restart rather
+than putting back what was on it.
+
+Every setting is available as an environment variable, so no config file is needed. Mount
+one at `/etc/readerboard/config.toml` if you would rather have it, in the format
+`packaging/config.example.toml` documents; the environment still wins over the file.
+
+For a sign on a cable rather than on the network, the container needs the device passed
+in and needs to be in the group that owns it. The group has to be given as a number,
+because the container has no `/etc/group` entry for the host's `dialout`:
+
+```
+stat -c '%G %g' /dev/ttyUSB0        # 20 on Debian and Raspberry Pi OS, 18 on Fedora
+docker run ... --device /dev/ttyUSB0 --group-add 20 \
+    -e READERBOARD_SERIAL_URL=/dev/ttyUSB0 ...
+```
+
 ## Using it
 
 Every write needs an `X-API-Key` header. `GET /health` does not.
@@ -177,6 +226,11 @@ registered, and it shares the sign the moment anything else registers.
 Settings come from `/etc/readerboard/config.toml`, overridden by environment variables
 prefixed `READERBOARD_`. `packaging/config.example.toml` documents every one of them.
 
+Every setting has both forms, and the container path relies on it: `slot_count` in the
+file is `READERBOARD_SLOT_COUNT` in the environment. Under Docker the file is optional
+and usually absent, which is not an error. `READERBOARD_CONFIG_FILE` moves the file if
+you want it somewhere other than the default.
+
 The sign's address is a full pyserial URL in `serial_url`: `socket://192.168.2.51:4001`
 for an Ethernet to RS-232 adapter, `/dev/ttyUSB0` for a cable plugged straight in, or
 `loop://` to run the service with no sign attached.
@@ -205,6 +259,19 @@ Sensible precautions remain sensible:
 - The service runs as a dedicated system user under a hardened systemd unit, which is
   worth keeping rather than running it as root for convenience.
 
+Under Docker the same points apply, with different mechanisms:
+
+- The image runs as an unprivileged user, UID and GID 10001, not as root. A bind-mounted
+  state directory has to be owned by that number on the host.
+- An API key passed as an environment variable is visible to anyone who can run
+  `docker inspect` on the container, and to anything that reads the Compose file's
+  environment. Mounting a config file mode 0640 keeps it out of both.
+- Bind the published port to the loopback address, `-p 127.0.0.1:5001:5001`, unless
+  clients on other machines need to reach it.
+- Passing a serial device in with `--device` gives the container that device and nothing
+  else. It does not need `--privileged`, and giving it that would hand it every device on
+  the host.
+
 ## Development
 
 ```

{readerboard-0.1.2 → readerboard-0.1.3}/README.md

@@ -3,6 +3,8 @@
 [![CI](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml)
 [![Release](https://github.com/mjaksn/readerboard/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/release.yml)
 [![PyPI](https://img.shields.io/pypi/v/readerboard)](https://pypi.org/project/readerboard/)
+[![GHCR](https://img.shields.io/badge/ghcr.io-readerboard-blue)](https://github.com/mjaksn/readerboard/pkgs/container/readerboard)
+[![Docker Hub](https://img.shields.io/docker/v/mjaksn/readerboard?label=docker%20hub&sort=semver)](https://hub.docker.com/r/mjaksn/readerboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/readerboard/blob/main/LICENSE)
 
 An HTTP service that drives a BetaBrite Classic sign, either through a serial cable or
@@ -36,13 +38,14 @@ until it is released, after which the rotation resumes.
 - Python 3.11 or newer.
 - A BetaBrite Classic, reachable either at a serial device such as `/dev/ttyUSB0` or over
   the network through an Ethernet to RS-232 adapter at `socket://host:port`.
-- For the installer, a machine running systemd. The service itself runs anywhere Python
-  does; only `scripts/install.sh` is Linux specific.
+- Either a machine running systemd, for `scripts/install.sh`, or a container runtime, for
+  the published image. The service itself runs anywhere Python does; only the installer
+  is Linux specific.
 
 ## Try it without a sign
 
 `loop://` is pyserial's loopback, so the service will start and serve its API with
-nothing attached.
+nothing attached. From a checkout:
 
 ```
 pip install -e ".[dev]"
@@ -51,10 +54,22 @@ READERBOARD_SERIAL_URL=loop:// READERBOARD_API_KEY=dev-key \
     python -m readerboard
 ```
 
+Or without one:
+
+```
+docker run --rm -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=loop:// -e READERBOARD_API_KEY=dev-key \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
 Then open <http://127.0.0.1:5001/docs>.
 
 ## Installing it properly
 
+Two ways, which do the same job. Pick whichever suits the machine.
+
+### With systemd
+
 ```
 sudo scripts/install.sh --serial-url socket://192.168.2.51:4001
 ```
@@ -68,6 +83,40 @@ again after pulling a new version: your config file and key are left alone.
 your registered messages, so reinstalling puts the sign back as it was. Add `--purge` to
 remove those too.
 
+### With Docker
+
+The image is published to both registries on every release, for `linux/amd64`,
+`linux/arm64` and `linux/arm/v7`, so a Pi pulls the same tag an x86 server does.
+
+```
+docker run -d --name readerboard --restart unless-stopped -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=socket://192.168.2.51:4001 \
+    -e READERBOARD_API_KEY=YOUR-KEY \
+    -v readerboard-state:/var/lib/readerboard \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
+`packaging/docker-compose.yml` is the same thing as a Compose file, with the settings
+worth knowing about written out beside it.
+
+The volume is what matters here. The registered messages are persisted to
+`/var/lib/readerboard`, and without it the sign comes back empty after a restart rather
+than putting back what was on it.
+
+Every setting is available as an environment variable, so no config file is needed. Mount
+one at `/etc/readerboard/config.toml` if you would rather have it, in the format
+`packaging/config.example.toml` documents; the environment still wins over the file.
+
+For a sign on a cable rather than on the network, the container needs the device passed
+in and needs to be in the group that owns it. The group has to be given as a number,
+because the container has no `/etc/group` entry for the host's `dialout`:
+
+```
+stat -c '%G %g' /dev/ttyUSB0        # 20 on Debian and Raspberry Pi OS, 18 on Fedora
+docker run ... --device /dev/ttyUSB0 --group-add 20 \
+    -e READERBOARD_SERIAL_URL=/dev/ttyUSB0 ...
+```
+
 ## Using it
 
 Every write needs an `X-API-Key` header. `GET /health` does not.
@@ -135,6 +184,11 @@ registered, and it shares the sign the moment anything else registers.
 Settings come from `/etc/readerboard/config.toml`, overridden by environment variables
 prefixed `READERBOARD_`. `packaging/config.example.toml` documents every one of them.
 
+Every setting has both forms, and the container path relies on it: `slot_count` in the
+file is `READERBOARD_SLOT_COUNT` in the environment. Under Docker the file is optional
+and usually absent, which is not an error. `READERBOARD_CONFIG_FILE` moves the file if
+you want it somewhere other than the default.
+
 The sign's address is a full pyserial URL in `serial_url`: `socket://192.168.2.51:4001`
 for an Ethernet to RS-232 adapter, `/dev/ttyUSB0` for a cable plugged straight in, or
 `loop://` to run the service with no sign attached.
@@ -163,6 +217,19 @@ Sensible precautions remain sensible:
 - The service runs as a dedicated system user under a hardened systemd unit, which is
   worth keeping rather than running it as root for convenience.
 
+Under Docker the same points apply, with different mechanisms:
+
+- The image runs as an unprivileged user, UID and GID 10001, not as root. A bind-mounted
+  state directory has to be owned by that number on the host.
+- An API key passed as an environment variable is visible to anyone who can run
+  `docker inspect` on the container, and to anything that reads the Compose file's
+  environment. Mounting a config file mode 0640 keeps it out of both.
+- Bind the published port to the loopback address, `-p 127.0.0.1:5001:5001`, unless
+  clients on other machines need to reach it.
+- Passing a serial device in with `--device` gives the container that device and nothing
+  else. It does not need `--privileged`, and giving it that would hand it every device on
+  the host.
+
 ## Development
 
 ```

{readerboard-0.1.2 → readerboard-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.1.2"
+version = "0.1.3"
 description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -39,7 +39,16 @@ classifiers = [
 # is allowed to live.
 dependencies = [
     "fastapi>=0.141.1,<0.142",
-    "uvicorn[standard]>=0.52.1,<0.53",
+    # Plain uvicorn, not the "standard" extra. That extra exists to make a busy
+    # server faster, and nothing here is busy: this one answers a handful of
+    # requests and then waits on a 9600 baud serial line behind a deliberate
+    # inter-packet delay, so a faster event loop and HTTP parser buy nothing
+    # measurable. What they cost is real, though. uvloop, httptools and PyYAML
+    # publish no 32-bit arm wheel, and building all three from source under
+    # emulation was eight minutes of the container image's build. The extra also
+    # brought in websockets, for a surface this API does not have, and watchfiles,
+    # for a --reload this never runs with.
+    "uvicorn>=0.52.1,<0.53",
     "pydantic>=2.13.4,<3",
     "pydantic-settings>=2.15.0,<3",
     "pyserial>=3.5,<4",

{readerboard-0.1.2 → readerboard-0.1.3}/readerboard/__init__.py

@@ -7,4 +7,4 @@ and against the release tag, before anything is published. See
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

{readerboard-0.1.2 → readerboard-0.1.3/readerboard.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.1.2
+Version: 0.1.3
 Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
 Author: mjaksn
 License-Expression: MIT
@@ -27,7 +27,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi<0.142,>=0.141.1
-Requires-Dist: uvicorn[standard]<0.53,>=0.52.1
+Requires-Dist: uvicorn<0.53,>=0.52.1
 Requires-Dist: pydantic<3,>=2.13.4
 Requires-Dist: pydantic-settings<3,>=2.15.0
 Requires-Dist: pyserial<4,>=3.5
@@ -45,6 +45,8 @@ Dynamic: license-file
 [![CI](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/ci.yml)
 [![Release](https://github.com/mjaksn/readerboard/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/readerboard/actions/workflows/release.yml)
 [![PyPI](https://img.shields.io/pypi/v/readerboard)](https://pypi.org/project/readerboard/)
+[![GHCR](https://img.shields.io/badge/ghcr.io-readerboard-blue)](https://github.com/mjaksn/readerboard/pkgs/container/readerboard)
+[![Docker Hub](https://img.shields.io/docker/v/mjaksn/readerboard?label=docker%20hub&sort=semver)](https://hub.docker.com/r/mjaksn/readerboard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/readerboard/blob/main/LICENSE)
 
 An HTTP service that drives a BetaBrite Classic sign, either through a serial cable or
@@ -78,13 +80,14 @@ until it is released, after which the rotation resumes.
 - Python 3.11 or newer.
 - A BetaBrite Classic, reachable either at a serial device such as `/dev/ttyUSB0` or over
   the network through an Ethernet to RS-232 adapter at `socket://host:port`.
-- For the installer, a machine running systemd. The service itself runs anywhere Python
-  does; only `scripts/install.sh` is Linux specific.
+- Either a machine running systemd, for `scripts/install.sh`, or a container runtime, for
+  the published image. The service itself runs anywhere Python does; only the installer
+  is Linux specific.
 
 ## Try it without a sign
 
 `loop://` is pyserial's loopback, so the service will start and serve its API with
-nothing attached.
+nothing attached. From a checkout:
 
 ```
 pip install -e ".[dev]"
@@ -93,10 +96,22 @@ READERBOARD_SERIAL_URL=loop:// READERBOARD_API_KEY=dev-key \
     python -m readerboard
 ```
 
+Or without one:
+
+```
+docker run --rm -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=loop:// -e READERBOARD_API_KEY=dev-key \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
 Then open <http://127.0.0.1:5001/docs>.
 
 ## Installing it properly
 
+Two ways, which do the same job. Pick whichever suits the machine.
+
+### With systemd
+
 ```
 sudo scripts/install.sh --serial-url socket://192.168.2.51:4001
 ```
@@ -110,6 +125,40 @@ again after pulling a new version: your config file and key are left alone.
 your registered messages, so reinstalling puts the sign back as it was. Add `--purge` to
 remove those too.
 
+### With Docker
+
+The image is published to both registries on every release, for `linux/amd64`,
+`linux/arm64` and `linux/arm/v7`, so a Pi pulls the same tag an x86 server does.
+
+```
+docker run -d --name readerboard --restart unless-stopped -p 5001:5001 \
+    -e READERBOARD_SERIAL_URL=socket://192.168.2.51:4001 \
+    -e READERBOARD_API_KEY=YOUR-KEY \
+    -v readerboard-state:/var/lib/readerboard \
+    ghcr.io/mjaksn/readerboard:latest
+```
+
+`packaging/docker-compose.yml` is the same thing as a Compose file, with the settings
+worth knowing about written out beside it.
+
+The volume is what matters here. The registered messages are persisted to
+`/var/lib/readerboard`, and without it the sign comes back empty after a restart rather
+than putting back what was on it.
+
+Every setting is available as an environment variable, so no config file is needed. Mount
+one at `/etc/readerboard/config.toml` if you would rather have it, in the format
+`packaging/config.example.toml` documents; the environment still wins over the file.
+
+For a sign on a cable rather than on the network, the container needs the device passed
+in and needs to be in the group that owns it. The group has to be given as a number,
+because the container has no `/etc/group` entry for the host's `dialout`:
+
+```
+stat -c '%G %g' /dev/ttyUSB0        # 20 on Debian and Raspberry Pi OS, 18 on Fedora
+docker run ... --device /dev/ttyUSB0 --group-add 20 \
+    -e READERBOARD_SERIAL_URL=/dev/ttyUSB0 ...
+```
+
 ## Using it
 
 Every write needs an `X-API-Key` header. `GET /health` does not.
@@ -177,6 +226,11 @@ registered, and it shares the sign the moment anything else registers.
 Settings come from `/etc/readerboard/config.toml`, overridden by environment variables
 prefixed `READERBOARD_`. `packaging/config.example.toml` documents every one of them.
 
+Every setting has both forms, and the container path relies on it: `slot_count` in the
+file is `READERBOARD_SLOT_COUNT` in the environment. Under Docker the file is optional
+and usually absent, which is not an error. `READERBOARD_CONFIG_FILE` moves the file if
+you want it somewhere other than the default.
+
 The sign's address is a full pyserial URL in `serial_url`: `socket://192.168.2.51:4001`
 for an Ethernet to RS-232 adapter, `/dev/ttyUSB0` for a cable plugged straight in, or
 `loop://` to run the service with no sign attached.
@@ -205,6 +259,19 @@ Sensible precautions remain sensible:
 - The service runs as a dedicated system user under a hardened systemd unit, which is
   worth keeping rather than running it as root for convenience.
 
+Under Docker the same points apply, with different mechanisms:
+
+- The image runs as an unprivileged user, UID and GID 10001, not as root. A bind-mounted
+  state directory has to be owned by that number on the host.
+- An API key passed as an environment variable is visible to anyone who can run
+  `docker inspect` on the container, and to anything that reads the Compose file's
+  environment. Mounting a config file mode 0640 keeps it out of both.
+- Bind the published port to the loopback address, `-p 127.0.0.1:5001:5001`, unless
+  clients on other machines need to reach it.
+- Passing a serial device in with `--device` gives the container that device and nothing
+  else. It does not need `--privileged`, and giving it that would hand it every device on
+  the host.
+
 ## Development
 
 ```

{readerboard-0.1.2 → readerboard-0.1.3}/readerboard.egg-info/requires.txt

@@ -1,5 +1,5 @@
 fastapi<0.142,>=0.141.1
-uvicorn[standard]<0.53,>=0.52.1
+uvicorn<0.53,>=0.52.1
 pydantic<3,>=2.13.4
 pydantic-settings<3,>=2.15.0
 pyserial<4,>=3.5

{readerboard-0.1.2 → readerboard-0.1.3}/tests/test_api.py

@@ -260,10 +260,17 @@ class TestUnreachableSign:
 
 
 class TestTheSimpleEndpoints:
-    """The exact payloads the example integrations in this repository send."""
+    """The payload shapes these endpoints accept, written out in full.
+
+    They exist for callers that post a fixed body to a fixed path, so the
+    bodies below are spelled out rather than built. A change that breaks one
+    of them breaks somebody's configuration file, which is exactly what these
+    tests are here to notice.
+    """
 
     def test_the_home_assistant_rest_command_payload(self, client):
-        # Home_Assistant_Sign_REST_Commands.yaml, with the template filled in.
+        # A temperature and the time, the common shape: a value from somewhere
+        # else, then <time> for the sign to fill in on its own.
         response = client.post(
             "/Write/Message",
             json={
@@ -280,7 +287,7 @@ class TestTheSimpleEndpoints:
         }
 
     def test_the_cron_line_payload(self, client):
-        # BetaBrite_Sign_Cron_Set_Time.txt sends SET_TIME with HHMM.
+        # SET_TIME takes the time as HHMM on a 24 hour clock.
         response = client.post(
             "/Write/ControlCommand",
             json={"command": "SET_TIME", "parameter": "2359"},

{readerboard-0.1.2 → readerboard-0.1.3}/tests/test_markup.py

@@ -25,8 +25,8 @@ def test_every_token_in_the_table_renders():
 
 
 def test_the_home_assistant_payload_renders():
-    # The exact shape Home_Assistant_Sign_REST_Commands.yaml sends, with the
-    # template already filled in.
+    # A temperature and the time, the common shape: a value from somewhere
+    # else, then <time> for the sign to fill in on its own.
     rendered = render("<green>18.4<degree> <red><time>")
     assert rendered == (
         c.TEXT_COLOR_GREEN + b"18.4" + c.XC_DEGREES + b" " + c.TEXT_COLOR_RED + c.CURTIME_INSERT