Skip to content

ci: publish the Docker image to Docker Hub on every release - #53

Merged
xiaodoudou merged 5 commits into
masterfrom
ci/docker-hub
Oct 18, 2026
Merged

xiaodoudou merged 5 commits into
masterfrom
ci/docker-hub

Conversation

@xiaodoudou

Copy link
Copy Markdown
Owner

docker pull xiaodoudoufr/plexiptv gave you 1.0.3, from 2018. Docker Hub's automated builds that made those images were retired, and nothing has published one since. The docs pointed every Docker user at it.

From the next version tag on, the release workflow builds and pushes the image itself.

What a tag publishes

Once the existing release job has passed (lint, tests, binaries), both images are built for amd64 and arm64 from a fresh checkout and pushed:

Dockerfile Tags
Dockerfile (Debian) 1.6.1, 1.6, latest
Dockerfile-alpine 1.6.1-alpine, 1.6-alpine, alpine

latest is named per variant on purpose: left on auto, the alpine build would push a plain latest as well and overwrite the Debian one. A manual run of the workflow builds no image.

A last job copies docs/docker.md to the Docker Hub page. It cannot fail the release.

The image itself

  • ffmpeg is included, with a font. RTSP and fragmented MP4 HLS play out of the box, and the slate for a failing channel has its text. Someone running the image has no way to add ffmpeg themselves. Compressed size: Debian 83 to 257 MB, Alpine 62 to 120 MB.
  • PUID and PGID. A host folder Docker creates for a bind mount belongs to root, so on a fresh install the app could not write settings.json and the container stopped. Unraid hits this every time. The container now starts as root just long enough to hand the config and log folders to PUID:PGID (1000:1000 by default), then runs PlexIPTV as that user with no capabilities and no new privileges. --user still works and skips all of it.
  • tini is the first process, so docker stop reaches node. CMD is node directly, since npm wants a writable home folder.
  • The app's code is now owned by root, so the app cannot rewrite itself.

One fix outside Docker: Alpine installs DejaVu in /usr/share/fonts/dejavu/, which the slate did not look in.

Tested

Docker is not on this Windows machine, so both images were built and run in WSL. Started on a root-owned folder as 99:100, the folder was handed over, node ran as uid 99 with no capabilities, the server answered and docker stop took under a second. A second start with the default PUID re-owned the folder to 1000, --user 1000:1000 worked, and a non-numeric PUID stopped with a clear message.

The new docker job in CI repeats the main checks on every pull request, so a broken Dockerfile fails here rather than after a tag.

npm run lint and npm test pass.

Before the next release

  • DOCKERHUB_TOKEN needs Read, Write & Delete scope for the Docker Hub page update. With the current Read & Write token the images still publish; only that last job fails.
  • The first image is published by the next version tag. Re-running 1.6.0 would use the old workflow file.

The slate shown when a channel cannot play draws its text with ffmpeg, which
needs a font file from a fixed list. Alpine's font-dejavu puts DejaVuSans.ttf
in /usr/share/fonts/dejavu/, which was not on it, so on Alpine the slate came
out with no words on it.
ffmpeg plays RTSP channels and fragmented MP4 HLS, and draws the slate shown
when a channel fails. Someone running the image cannot add it themselves, so
both images now ship it, with a font for the slate's text.

The image ran as the node user, uid 1000, from the start. A host folder that
Docker creates for a bind mount belongs to root, so on a fresh install the app
could not write settings.json and the container stopped. Unraid hits this on
every new install, and wants 99:100 besides.

The container now starts as root just long enough for docker/entrypoint.sh to
hand the config and log folders to PUID:PGID, 1000:1000 by default, and then
runs PlexIPTV as that user with setpriv: no supplementary groups, no
capabilities, no new privileges. Started with --user, it skips all that.

tini is now the first process. Node ignores docker stop when it is PID 1 and
has no handler, which npm used to paper over by forwarding the signal. CMD is
node itself, because npm wants a writable home folder an arbitrary PUID does
not have.

The code stays owned by root, so the app can no longer rewrite itself; only
the config and log folders are its own. .gitattributes keeps the entrypoint at
LF line endings, or a Windows checkout would break a locally built image.
The release publishes the images, so a Dockerfile that no longer builds, or an
image that no longer starts, should fail a pull request rather than a tag.

Each image is started the way Unraid starts it: on a folder owned by root,
asked to run as 99:100. The job checks it answers, that settings.json ends up
owned by 99:100, that node runs as uid 99, and that docker stop takes effect
at once.
xiaodoudoufr/plexiptv on Docker Hub still had the 2018 images from the old
automated builds, which Docker Hub has since retired, so docker pull gave you
1.0.3.

A version tag now builds both images for amd64 and arm64 once the release job
has passed, and pushes them: 1.6.1, 1.6 and latest from Dockerfile, and
1.6.1-alpine, 1.6-alpine and alpine from Dockerfile-alpine. latest is named per
variant, because left to metadata-action the alpine build would push a plain
latest too and overwrite the Debian one. A manual run builds no image.

A last job copies docs/docker.md to the Docker Hub page. Docker Hub refuses
that without a token carrying Delete scope, and the images are out by then, so
its failure is reported without failing the release.
docs/docker.md was two sentences pointing at a 2018 image. It now covers the
tags, running with docker run or Compose, PUID and PGID, the first start and
the dashboard password, adding the tuner to Plex from a bridged container,
ffmpeg, keeping the logs, and updating.

The page doubles as the Docker Hub description, so its links are absolute: the
action that copies it there would resolve relative ones against the repository
root rather than docs/.
@xiaodoudou
xiaodoudou merged commit ac4a7fd into master Oct 18, 2026
7 checks passed
@xiaodoudou
xiaodoudou deleted the ci/docker-hub branch October 18, 2026 05:12
@xiaodoudou xiaodoudou mentioned this pull request Oct 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant