pulse-signage/README.md

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
• Manage roles and permissions for the admin web UI
• Upload images and other media for use in slides and templates
• View live screen connections and send player commands

Admin permissions are split into CRUD actions per section, so you can grant read-only, editor, creator, or delete access separately.

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

The first admin account is placed into the built-in Administrators role, which has full web-admin access through the CRUD permissions.

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. The list below matches the provided .env.example file.

Compose and Shared Settings

• PULSE_SIGNAGE_IMAGE - image tag used by the published Compose setup, default git.lzstealth.com/lzstealth/pulse-signage:latest
• PULSE_SIGNAGE_SHARED_SECRET - shared secret used to sign player page API fetches and server-to-player requests; page tokens auto-renew while the page stays active and request signatures must be fresh; leave unset to keep the auth checks disabled for compatibility

Database Connection

• DB_HOST - MySQL host, default mysql
• DB_PORT - MySQL port, default 3306
• DB_NAME - database name, default pulse-signage
• DB_USER - database user, default pulse-signage
• DB_PASSWORD - database password, default signage_password
• MYSQL_ROOT_PASSWORD - root password for the bundled MySQL container, default root_password

Player App

• PLAYER_INTERNAL_BASE_URL - internal player URL used by the web app, default http://player:8081
• PLAYER_PUBLIC_BASE_URL - public player URL used by browser-facing links, default http://localhost:8081

Web App

• SESSION_MAX_AGE_DAYS - admin session lifetime in days, default 14
• DASHBOARD_REFRESH_INTERVAL_MS - dashboard refresh interval in milliseconds, default 2000
• DEFAULT_ADMIN_USERNAME - username used for the initial admin account, default admin
• DEFAULT_ADMIN_NAME - display name used for the initial admin account, default Admin
• DEFAULT_ADMIN_PASSWORD - password used for the initial admin account, default admin
• PASSWORD_HASH_ITERATIONS - password hash iteration count, default 310000

Docker Compose

The repository includes a docker-compose.yml file that starts three services:

• web - the admin app exposed on container port 8080
• player - the signage player exposed on container port 8081
• mysql - the database on port 3306

Change the published host ports in Docker Compose if you want different external ports; the app containers listen on 8080 and 8081 internally.

By default, web and player use the published image from git.lzstealth.com/lzstealth/pulse-signage:latest. You can point both services at a specific release by setting PULSE_SIGNAGE_IMAGE to a tagged image such as git.lzstealth.com/lzstealth/pulse-signage:v1.0.0.

The Compose file also defines a shared media volume for stored assets and a mysql_data volume for database persistence.

In Docker, media storage is controlled by the media volume mount at /app/media. Outside Docker, the web app and player do not have to use the same upload location or even the same server, as long as each service can access its own configured media path.

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.
• If PULSE_SIGNAGE_SHARED_SECRET is set, the web and player containers must use the same value, and any reverse proxy in front of the player must forward /api/media/... without rewriting the path.
• Uploaded media is stored separately from the application source, so make sure it is backed up if you are not using Docker volumes.
• The player page uses the browser Screen Wake Lock API when available, but kiosk mode and OS sleep settings still matter because the browser can deny or release the wake lock.

Documentation

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

Database schema details live in docs/schema.md. It summarizes the current tables created at startup.

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