TrmnlTelegram
TRMNL is a networked e-ink display device that shows content through integrations. Getting an arbitrary document onto it normally means building a custom plugin. trmnl-telegram is a self-hosted bridge that turns a Telegram chat into the input channel: a user sends an image, PDF, or EPUB to a bot and it renders to the device. The project is a small MIT-licensed Python tool.
Assess. The repository is a convenience bridge for one specific device, small in scope and adoption (11 stars, last pushed September 2025, no open issues at the time of writing). Outer position reflects the niche use case, low adoption, and the absence of first-person production use; it is worth exploring rather than committing to.
- Receives files through a Telegram bot, with an optional user-ID allowlist for access control.
- Converts EPUB files to PDF, then extracts PDF pages as images with page navigation.
- Pushes rendered images to TRMNL through a Private Plugin webhook.
- Deploys via Docker, uses uv for dependency management, and supports configurable display dimensions (default 480x800).
trmnl-telegram runs as a persistent process that long-polls Telegram for messages. It is not ephemeral and does not fit a scheduled or serverless host: PDF page navigation uses interactive buttons, and each button press is a live callback the process must answer within seconds. A fire-and-forget host can push a single page but loses navigation. Practical deployment is an always-on host, such as a small VPS, a home device, or a hobby-tier container platform, using the project's Docker Compose file.
The intended way to trial this on an always-on host, recorded so the decisions do not have to be re-derived later. Not yet executed; running the bot in production against this pipeline is the gate to promote this blip to Trial.
The approach is a manual "image-mirror and reconcile" pipeline: because upstream
ships no published image, a CI job builds the tool's source into a private
registry image, and a deploy job reconciles it onto the host with an idempotent
docker compose up -d. The build runs off the host, so the small VPS stays a
pull-only target.
| Decision | Choice | Why |
|---|---|---|
| CI platform | GitLab CI on the self-hosted dbmacm3 runner |
Reuses the existing SSH-to-host deploy precedent |
| Registry | GHCR, image tagged by upstream commit SHA | Traceable, rollback-able; SHA tag enables the skip check |
| Idempotent build | Skip build+push if the SHA image already exists | Unchanged upstream is a no-op end to end |
| Trigger | Manual | No push to react to; upstream is third-party |
| Build source | Build from src/ in CI |
Upstream ships no prebuilt image (build: ./src/.) |
| Deploy auth | SSH as root by key | Non-interactive; sudo has no TTY in a pipeline |
| Reconcile |
docker compose up -d against the pinned tag |
No-op if current, self-heals if the container died |
| Reboot survival | restart: unless-stopped |
Container returns after a host reboot, no pipeline run |
| Secrets | Bot token + plugin UUID in the lpass global/env note |
Never baked into the image or the repo |
The runnable pipeline (.gitlab-ci.yml, image-based compose, CI/CD variables)
will live in a separate deployment repository; this section records the
reasoning, not the executable spec.
The bridge removes the need to hand-build a plugin for the common case of pushing a document or image to a TRMNL screen, using a chat app most people already have open.
