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

docs: update deployment and API references

Browse Source
This commit is contained in:
lzstealth
2026-09-04 21:39:28 +01:00
parent 954e0edc3f
commit ed2f23bb5d
5 changed files with 229 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docker-compose/README.md
+112 -61
View File
@@ -2,6 +2,21 @@
This folder contains the Docker Compose definitions for Pulse Signage, including the public stack and the remote player stack.
## Contents
- [Files](#files)
- [Stack Overview](#stack-overview)
- [Services](#services)
- [Environment Files](#environment-files)
- [Public Stack Setup](#public-stack-setup)
- [Remote Player Setup](#remote-player-setup)
- [Shared Secret](#shared-secret)
- [Ports](#ports)
- [Volumes](#volumes)
- [Networks](#networks)
- [Notes](#notes)
- [Deployment Checklist](#deployment-checklist)
## Files
- [docker-compose.yml](docker-compose.yml) - full public stack with web, player, player bridge, and MySQL.
@@ -45,6 +60,8 @@ Key configuration:
- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
- `PULSE_SIGNAGE_SHARED_SECRET`
- `WEB_PUBLIC_URL`
- `BRIDGE_INTERNAL_URL`
- `DEFAULT_ADMIN_USERNAME`
- `DEFAULT_ADMIN_NAME`
- `DEFAULT_ADMIN_PASSWORD`
@@ -62,11 +79,13 @@ Responsibilities:
Key configuration:
- `PLAYER_PUBLIC_URL`
- `PLAYER_INTERNAL_URL`
- `PLAYER_IDENTIFIER`
- `BRIDGE_PUBLIC_URL` in remote mode
- `PULSE_SIGNAGE_SHARED_SECRET`
- database settings in local mode
- `WEB_PUBLIC_URL`
- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD` in local mode
### `player-bridge`
@@ -96,46 +115,106 @@ Responsibilities:
Key configuration:
- `MYSQL_DATABASE`
- `MYSQL_USER`
- `MYSQL_PASSWORD`
- `DB_NAME`
- `DB_USER`
- `DB_PASSWORD`
- `MYSQL_ROOT_PASSWORD`
## Environment Files
### `.env.example`
| File | Used by | How it is loaded |
| --- | --- | --- |
| `.env.example` | Public stack | Copy to `.env`; Compose loads it automatically, or pass it with `--env-file`. |
| `.env.remote.example` | Published remote player | Copy to `.env.remote`; pass it with `--env-file .env.remote`. |
Use this file as a starting point for the public compose stack.
The example files are templates. Copy the appropriate file, review its defaults, and replace secrets or placeholder URLs before deploying.
### Public stack: `.env.example`
Use this file as a starting point for the public Compose stack.
Important values:
- `PULSE_SIGNAGE_WEB_IMAGE` - image to run for the web app and bridge services, typically `.../pulse-signage-web:latest`
- `PULSE_SIGNAGE_PLAYER_IMAGE` - image to run for the player services, typically `.../pulse-signage-player:latest`
- `PULSE_SIGNAGE_SHARED_SECRET` - long random secret shared by the web, player, and bridge services for authenticated requests
- `DB_*` - MySQL credentials and database name for the stack
- `MYSQL_ROOT_PASSWORD` - root password for the local MySQL container
- `WEB_PUBLIC_URL` - public URL of the web application
- `WEB_INTERNAL_URL` - internal URL the bridge uses to call the web app directly
- `PLAYER_IDENTIFIER` - unique local player identifier
- `PLAYER_PUBLIC_URL` - URL used by the kiosk launcher and direct player access
- `PLAYER_INTERNAL_URL` - internal URL the web app uses for local player calls
- `BRIDGE_INTERNAL_URL` - bridge URL the web app uses for player snapshot and command forwarding
- `DEFAULT_ADMIN_*` - bootstrap admin account values
| Variable | Purpose | Default |
| --- | --- | --- |
| `PULSE_SIGNAGE_WEB_IMAGE` | Image for the web app and bridge services. | `git.lzstealth.com/lzstealth/pulse-signage-web:latest` |
| `PULSE_SIGNAGE_PLAYER_IMAGE` | Image for the player services. | `git.lzstealth.com/lzstealth/pulse-signage-player:latest` |
| `PULSE_SIGNAGE_SHARED_SECRET` | Shared request-signing secret. | Blank; set this for a secured deployment. |
| `DB_HOST` | MySQL host name. | `mysql` |
| `DB_PORT` | MySQL port. | `3306` |
| `DB_NAME` | MySQL database name. | `pulse-signage` |
| `DB_USER` | MySQL user name. | `pulse-signage` |
| `DB_PASSWORD` | MySQL user password. | `signage_password` |
| `MYSQL_ROOT_PASSWORD` | Local MySQL root password. | `root_password` |
| `WEB_PUBLIC_URL` | Public URL of the web application. | `http://localhost:8080` |
| `WEB_INTERNAL_URL` | Internal URL the bridge uses to call the web app. | `http://web:8080` |
| `PLAYER_IDENTIFIER` | Unique local player identifier. | `player-local` |
| `PLAYER_PUBLIC_URL` | URL used by the kiosk launcher and direct player access. | `http://localhost:8081` |
| `PLAYER_INTERNAL_URL` | Internal URL used for local player calls. | `http://player:8081` |
| `BRIDGE_INTERNAL_URL` | Bridge URL used for snapshots and command forwarding. | `http://player-bridge:8090` |
| `DEFAULT_ADMIN_USERNAME` | Bootstrap admin username. | `admin` |
| `DEFAULT_ADMIN_NAME` | Bootstrap admin display name. | `Admin` |
| `DEFAULT_ADMIN_PASSWORD` | Bootstrap admin password. | `password123!` |
### `.env.remote.example`
### Remote player: `.env.remote.example`
Use this file on a remote player device.
Use this file as the starting point for a remote player device. The production remote Compose file reads values from Compose's environment, so pass the copied file explicitly with `--env-file`.
Important values:
- `PULSE_SIGNAGE_PLAYER_IMAGE` - image to run on the device, typically `.../pulse-signage-player:latest`
- `PULSE_SIGNAGE_SHARED_SECRET` - must match the public stack and should be the same long random value used everywhere in the deployment
- `PLAYER_IDENTIFIER` - unique remote player identifier
- `PLAYER_PUBLIC_URL` - optional URL used by the kiosk launcher when the remote player is directly reachable
- `BRIDGE_PUBLIC_URL` - bridge URL the player connects back to
- `PLAYER_AGENT_RECONNECT_DELAY_MS` - reconnect delay for the player agent
| Variable | Purpose | Default |
| --- | --- | --- |
| `PULSE_SIGNAGE_PLAYER_IMAGE` | Image to run on the device. | `git.lzstealth.com/lzstealth/pulse-signage-player:latest` |
| `PULSE_SIGNAGE_SHARED_SECRET` | Shared request-signing secret; must match the public stack. | Blank; set it to the public stack's secret. |
| `PLAYER_IDENTIFIER` | Unique remote player identifier. | `player-remote` |
| `PLAYER_PUBLIC_URL` | Optional URL for direct player access. | `http://remote-player.example.com:8081` |
| `BRIDGE_PUBLIC_URL` | Bridge URL the player connects back to. | `http://player-bridge.example.com:8090`; replace this placeholder. |
| `PLAYER_AGENT_RECONNECT_DELAY_MS` | Delay before reconnecting to the bridge. | `5000` |
### `PULSE_SIGNAGE_SHARED_SECRET`
## Public Stack Setup
Install Docker Engine with Docker Compose, then run the public stack from this directory:
```sh
cp .env.example .env
docker compose -f docker-compose.yml up -d
```
The command pulls the published images, creates the network and volumes, and starts the web app, local player, player bridge, and MySQL services. Check the installation with:
```sh
docker compose -f docker-compose.yml ps
docker compose -f docker-compose.yml logs -f web
```
## Remote Player Setup
A remote deployment has two parts:
- the public stack runs the web app, database, and player bridge
- each remote device runs only the player and connects back to the bridge
The remote player does not need database credentials. Set `BRIDGE_PUBLIC_URL` to the externally reachable bridge URL, including its port when required. It must point to the bridge service, not the web dashboard URL. The bridge must be reachable from the device and allow both HTTP requests and the player websocket connection at `/ws/players`.
### Published remote player
On the remote device:
```sh
cp .env.remote.example .env.remote
docker compose --env-file .env.remote -f docker-compose.remote.yml up -d
```
The published remote stack exposes the player on host port `8081`. Check its connection and startup output with:
```sh
docker compose --env-file .env.remote -f docker-compose.remote.yml ps
docker compose --env-file .env.remote -f docker-compose.remote.yml logs -f player
```
Start the public stack and confirm that its bridge is reachable before starting the remote player. Once the player connects, it should appear in the dashboard's Connected clients view. If it does not, verify the bridge URL, shared secret, firewall or reverse-proxy websocket support, and the player logs.
## Shared Secret
This secret is the shared signing key for requests between the services. Use a single value for every service that needs to talk to the same stack, including the web app, player, bridge, and any remote player that connects back to that bridge.
@@ -149,34 +228,6 @@ If you want a quick local value, generate one with a password manager or a comma
Leave it blank only if you intentionally want to run without request signing in a throwaway local setup.
## Main Configuration Variables
| Variable | Used By | Purpose |
| --- | --- | --- |
| `PULSE_SIGNAGE_WEB_IMAGE` | web, bridge | Docker image to run for the web app and bridge services. |
| `PULSE_SIGNAGE_PLAYER_IMAGE` | player, remote player | Docker image to run for the player services. |
| `PULSE_SIGNAGE_SHARED_SECRET` | web, player, bridge, remote player | Shared secret for authenticated requests between services. |
| `DB_HOST` | web, player, bridge | Database host name. |
| `DB_PORT` | web, player, bridge | Database port. |
| `DB_NAME` | web, player, bridge, mysql | Database name. |
| `DB_USER` | web, player, bridge, mysql | Database user. |
| `DB_PASSWORD` | web, player, bridge, mysql | Database password. |
| `MYSQL_ROOT_PASSWORD` | mysql | Root password for the local MySQL container. |
| `MYSQL_DATABASE` | mysql | Database name used by the local MySQL container. |
| `MYSQL_USER` | mysql | Database user used by the local MySQL container. |
| `MYSQL_PASSWORD` | mysql | Database password used by the local MySQL container. |
| `WEB_PUBLIC_URL` | web, player-bridge | Public URL of the web application. |
| `WEB_INTERNAL_URL` | player-bridge | Internal web URL used by the bridge to call the dashboard app directly. |
| `PLAYER_IDENTIFIER` | player | Stable player identifier. |
| `PLAYER_PUBLIC_URL` | player, remote player | URL used by the kiosk launcher and direct player access; optional for bridge-only remote players. |
| `PLAYER_INTERNAL_URL` | web, player | Internal player URL used by the dashboard and player runtime. |
| `BRIDGE_INTERNAL_URL` | web | Bridge URL used by the web app for player snapshot and command forwarding. |
| `DEFAULT_ADMIN_USERNAME` | web | Bootstrap admin username. |
| `DEFAULT_ADMIN_NAME` | web | Bootstrap admin display name. |
| `DEFAULT_ADMIN_PASSWORD` | web | Bootstrap admin password. |
| `BRIDGE_PUBLIC_URL` | remote player | URL of the bridge service. |
| `PLAYER_AGENT_RECONNECT_DELAY_MS` | remote player | Delay before reconnecting to the bridge. |
## Ports
Public stack ports:
@@ -210,16 +261,16 @@ Each compose file creates its own named network:
## Notes
- The public stack expects the app services and MySQL to share the same `PULSE_SIGNAGE_SHARED_SECRET`.
- The public stack expects the web, player, and bridge services to share the same `PULSE_SIGNAGE_SHARED_SECRET`.
- A remote player must use the same `PULSE_SIGNAGE_SHARED_SECRET` as the bridge it connects to.
- The bridge service is the dashboard-facing command path for connected remote players.
- The remote player should point `BRIDGE_PUBLIC_URL` at the bridge, not at the public web endpoint.
- The `PULSE_SIGNAGE_WEB_IMAGE` and `PULSE_SIGNAGE_PLAYER_IMAGE` tags default to the published `pulse-signage-web` and `pulse-signage-player` repositories with `latest` tags, but they can be overridden for custom releases.
## Recommended Setup
## Deployment Checklist
1. Copy `.env.example` to a local `.env` file for the public stack.
2. Copy `.env.remote.example` to a device-specific `.env` file for the remote player.
3. Make sure `PULSE_SIGNAGE_SHARED_SECRET` matches everywhere.
4. Start the public stack first, then start the remote player after the bridge is reachable.
1. Follow [Public Stack Setup](#public-stack-setup) to start the public stack with Docker Compose.
2. Set the same `PULSE_SIGNAGE_SHARED_SECRET` in the public and remote environments.
3. Set `BRIDGE_PUBLIC_URL` to the externally reachable bridge URL.
4. Start the published remote player with the workflow above.
5. Verify that the player appears in Connected clients before testing screen commands.