Digital Signage Deployment with PiSignage

Prerequisites

• Docker and buildx installed on your personal computer.
• X11 installed on your ALPON — see Running GUI Apps with X11 in Containers.

To run PiSignage on ALPON, you build both the server and player images. Sixfab has containerized these applications to run on ALPON devices; the Dockerfiles are included below.

1. 1

   Build the server image

   Run these steps on your personal computer, where Docker and buildx are installed. Create a directory for the server:

   bash · create directory

   mkdir pisignage-server
   cd pisignage-server

   Create a Dockerfile with a maintained Node.js base and require a reviewed PiSignage server tag or commit:

   Dockerfile · server

   FROM node:22-alpine3.21
   ARG PISIGNAGE_SERVER_REF
   
   RUN test -n "$PISIGNAGE_SERVER_REF" \
       && apk add --no-cache bash git ffmpeg imagemagick
   
   ENV NODE_ENV=production
   WORKDIR /pisignage-server
   
   RUN git clone https://github.com/colloqi/pisignage-server.git . \
       && git checkout "$PISIGNAGE_SERVER_REF" \
       && npm ci --omit=dev \
       && chmod +x ./wait-for-it.sh
   
   CMD ["./wait-for-it.sh", "127.0.0.1:27017", "--", "node", "server.js"]

   Build the server image:

   bash · build server

   docker buildx build --load --platform linux/arm64 --build-arg PISIGNAGE_SERVER_REF=<reviewed-tag-or-commit> -t pisignage-server:<version> .

2. 2

   Build the player image

   Create a directory for the player:

   bash · create directory

   mkdir pisignage-player
   cd pisignage-player

   Create a Dockerfile that verifies the Player2 archive before installation and runs Chromium as a non-root user. Obtain the current ARM64 archive URL and SHA-256 from PiSignage; do not reuse an unverified download.

   Dockerfile · player

   FROM debian:bookworm-slim
   ARG PLAYER_URL
   ARG PLAYER_SHA256
   
   RUN test -n "$PLAYER_URL" && test -n "$PLAYER_SHA256" \
       && apt-get update \
       && apt-get install -y --no-install-recommends ca-certificates curl unzip chromium nodejs npm sudo \
       && rm -rf /var/lib/apt/lists/*
   
   WORKDIR /opt/pisignage
   RUN curl -fL "$PLAYER_URL" -o /tmp/player.zip \
       && echo "$PLAYER_SHA256  /tmp/player.zip" | sha256sum -c - \
       && unzip /tmp/player.zip \
       && rm /tmp/player.zip \
       && cp player2/build-scripts/install-pisignage.sh . \
       && chmod +x install-pisignage.sh player2/build-scripts/* player2/shell-scripts/* \
       && ./install-pisignage.sh \
       && useradd --create-home --uid 1000 pisignage \
       && chown -R pisignage:pisignage /opt/pisignage
   
   USER pisignage
   CMD ["./start.sh"]

   Build the player image:

   bash · build player

   docker buildx build --load --platform linux/arm64 --build-arg PLAYER_URL=<official-arm64-archive-url> --build-arg PLAYER_SHA256=<published-sha256> -t pisignage-player:<version> .

3. 3

   Push both images to the Sixfab Container Registry

   Upload both images so they're available to the device:

   • Open the Sixfab Container Registry page.
   • Click + Add Container and follow the prompts for each image.
4. 4

   Deploy the containers

   Deploy three containers from the Applications tab of your asset, in order.

   1 · MongoDB

   • Click + Deploy, enter a container name, and check “I would like to use my own container path”.
   • Select a currently supported ARM64 MongoDB image that meets PiSignage's documented database compatibility. Do not use the retired MongoDB 4.4 image from older revisions of this guide.
   • Enable Host Network, then click Deploy.

   2 · PiSignage server

   • Click + Deploy, enter a container name, and select the server image and tag.
   • Enable Host Network, then click Deploy.

   3 · PiSignage Player2

   Grant the container's local root identity access to the graphical session. Do not use xhost +, which disables X11 access control globally. See Running GUI Apps with X11 in Containers for the persistent service and revocation steps.

   bash · grant scoped X11 access

   DISPLAY=:0 XAUTHORITY=/root/.Xauthority xhost +SI:localuser:root

   Then click + Deploy, enter a container name, and select the Player2 image and tag. Add this environment variable:

   DISPLAY :0

   Add the X11 socket and authorization file as read-only bind mounts. Audio remains read/write:

   X11 socket (read-only) /tmp/.X11-unix → /tmp/.X11-unix

   .Xauthority (read-only) /root/.Xauthority → /root/.Xauthority

   Audio (read/write) /dev/snd → /dev/snd

   Enable Host Network. Leave Privileged disabled unless Player2 cannot access the required hardware through the configured paths; if enabled, treat the container as host-trusted. Then click Deploy.

5. 5

   Verify the deployment

   • Check the device's main screen to confirm Player2 is running in fullscreen.
   • In a browser, open ports 3000 and 8000 at the device's IP to confirm the server and player are up.
   • To use the local server, update the server address in the Player2 interface (port 8000) to 127.0.0.1:3000 — otherwise the device keeps talking to the default main server.

Troubleshooting

Make sure a display is physically connected. Without one, xhost + fails to open the display:

xhost: unable to open display ""

If a display is connected, export the variable and retry:

export DISPLAY=:0