LZStealth/pulse-signage
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Activity

Update README.md

Browse Source
This commit is contained in:
LZStealth
2026-07-27 11:53:31 +01:00
parent de1469c29d
commit 9e51052b7f
1 changed files with 68 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+68 -66
View File
@@ -1,92 +1,94 @@
# Pulse Signage
Pulse Signage is a digital signage system that lets you manage screens, playlists, slides, templates, and uploaded media from one admin interface.
Pulse Signage is a digital signage platform with two connected services:
It runs as two connected services:
- a web admin app for managing content, screens, media, and permissions
- a player app that renders the active signage on each screen and handles live updates
- 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
The project is built around playlists, slides, templates, canvas sizes, uploaded media, and role-based access control. Screens register to the player, receive playback state from the server, and can be updated in real time from the admin interface.
## 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.
## Documentation
Player-facing API details live in [docs/api.md](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](docs/websocket.md). It covers the player control socket, snapshot stream, and the command/message shapes the player accepts.
## What You Need
## Requirements
- Docker and Docker Compose
- A MySQL database
- MySQL / MariaDB
## First-Time Setup
## Quick Start
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.
The easiest way to run the stack is with Docker Compose.
- Username: `admin`
- Password: `admin`
1. Set any environment variables you want to override.
2. Run `docker compose up -d`.
3. Open the web admin app on port `3000` and the player on port `3001`.
The first admin account is placed into the built-in `Administrators` role, which has full web-admin access through the CRUD permissions.
By default, the compose file uses `git.lzstealth.com/lzstealth/pulse-signage:latest` for both app services.
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`
- `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
### Player App
- `PLAYER_PORT` - player port, default `3001`
Before starting, copy `.env.example` to `.env` and adjust the values for your setup.
## Docker Compose
The repository includes a `docker-compose.yml` file that starts three services:
The included `docker-compose.yml` starts three services:
- `web` - the admin app on port `3000`
- `player` - the signage player on port `3001`
- `mysql` - the database on port `3306`
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:
The Compose file also defines a shared `media` volume for stored assets and a `mysql_data` volume for database persistence.
- a shared `media` volume for uploaded assets and generated thumbnails
- 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.
In Docker, media is mounted at `/app/media` for both app services.
## Important Notes
## First-Time Setup
On first launch, the app creates the required database tables and seeds a default administrator if no users exist yet.
- Username: `admin`
- Password: `admin`
You can override the seeded admin credentials with these environment variables:
- `DEFAULT_ADMIN_USERNAME`
- `DEFAULT_ADMIN_NAME`
- `DEFAULT_ADMIN_PASSWORD`
## More Details
### Configuration
#### Database
- `DB_HOST` - MySQL or MariaDB host, default `127.0.0.1`
- `DB_PORT` - MySQL or MariaDB port, default `3306`
- `DB_NAME` - database name, default `signage`
- `DB_USER` - database user, default `signage_user`
- `DB_PASSWORD` - database password, default `signage_password`
The default database container uses MySQL 8.4, but the app can also run against a compatible MariaDB server if you swap the image.
#### 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`
- `PULSE_SIGNAGE_SHARED_SECRET` - shared secret used to sign player page API fetches and server-to-player requests; leave unset to disable the auth checks for compatibility
- `SESSION_MAX_AGE_DAYS` - admin session lifetime, default `14`
- `DASHBOARD_REFRESH_INTERVAL_MS` - dashboard refresh interval, default `2000`
#### Player App
- `PLAYER_PORT` - player port, default `3001`
### Documentation
- [Player API](docs/api.md)
- [Player websocket behavior](docs/websocket.md)
### 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.
- The web and player services can run separately, and they do not need to share the same upload mount as long as each service can access its own configured media path.
- If `PULSE_SIGNAGE_SHARED_SECRET` is set, the web and player services 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 back it 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.