Pulse Signage

Pulse Signage is a digital signage system that lets you manage screens, playlists, slides, templates, and uploaded media from one admin interface.

It runs as two connected services:

• the web admin app for managing content and screens
• the player app that shows the current signage on each screen and listens for live updates

What You Can Do

• Sign in to the admin dashboard
• Create and organize playlists and slides
• Design reusable templates and canvas sizes
• Register screens and assign playlists to them
• Upload images and other media for use in slides and templates
• View live screen connections and send player commands

Documentation

Player-facing API details live in docs/api.md. It covers the player HTTP endpoints for screen playback, playlist data, connections, and commands.

Player websocket behavior lives in docs/websocket.md. It covers the player control socket, snapshot stream, and the command/message shapes the player accepts.

What You Need

• Docker and Docker Compose
• A MySQL database

First-Time Setup

When the app starts for the first time, it creates the database tables it needs and adds a default admin account if no users exist yet.

• Username: admin
• Password: admin

You can change the initial admin credentials with these optional environment variables:

• DEFAULT_ADMIN_USERNAME
• DEFAULT_ADMIN_NAME
• DEFAULT_ADMIN_PASSWORD

Configuration

The app reads its settings from environment variables.

Database Connection

• DB_HOST - MySQL host, default 127.0.0.1
• DB_PORT - MySQL port, default 3306
• DB_NAME - database name, default signage
• DB_USER - database user, default signage_user
• DB_PASSWORD - database password, default signage_password

Web Admin App

• WEB_PORT - admin app port, default 3000
• PLAYER_INTERNAL_BASE_URL - player address used by the server, default http://player:3001
• PLAYER_PUBLIC_BASE_URL - player address shown in browser links, default http://localhost:3001
• UPLOAD_DIR - storage location for uploaded files, default ./uploads

Player App

• PLAYER_PORT - player port, default 3001

Using Docker

The recommended way to run the project is with Docker Compose.

npm run docker:up

The main Compose file now uses the published Docker image and still reads values from the repository .env file. DB_HOST comes from that file for the app containers, so you can point the web UI and player at an external database host or change it to mysql if you want to use the bundled MySQL service.

If you only want to test the image build from the current checkout without using Compose, run:

npm run docker:build

To publish the Docker image to the Gitea container registry, push to main or create a v* tag. The workflow in .gitea/workflows/docker-publish.yml builds git.lzstealth.com/LZStealth/pulse-signage and pushes latest, sha, and tagged releases.

This starts:

• the web admin app on port 3000
• the player app on port 3001
• MySQL on port 3306

The web app and player app share the same uploaded media volume, so files uploaded in the admin UI are available to the player.

If you want to stop the stack later, run npm run docker:down. To follow logs, run npm run docker:logs.

Important Notes

• The web app must be able to reach the player through PLAYER_INTERNAL_BASE_URL.
• When running in Docker, that value should point to the Docker service name, not localhost.
• Uploaded media is stored separately from the application source, so make sure it is backed up if you are not using Docker volumes.