Release v2.4.2

README.md

@@ -1,104 +1,81 @@
 # 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 self-hosted digital signage platform built for teams that want clear, flexible control over what appears on every screen.
 
-It runs as two connected services:
+It gives you one place to manage playlists, slides, templates, screen assignments, announcements, data-driven content, and live player control without handing that workflow to a third-party service.
 
-- 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
+## Why It Stands Out
 
-## What You Can Do
+- Keep signage under your own control.
+- Build polished screen experiences with reusable templates and playlists.
+- Push announcements, schedules, RSS feeds, API content, and other dynamic content to screens.
+- See what is live, what is queued, and what needs attention from a single admin dashboard.
+- Use the same system for everyday signage, timed messages, and more structured information displays.
 
-- 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
+## What It Handles
 
-Admin permissions are split into CRUD actions per section, so you can grant read-only, editor, creator, or delete access separately.
+- Screens and playlist assignments.
+- Slides, templates, and canvas sizes.
+- Announcements and screen-specific targeting.
+- RSS feeds, API sources, and schedule-based content.
+- Roles and permissions for admin access.
+- Background tasks and scheduled refresh jobs.
+- Player onboarding and live playback control.
 
-## What You Need
+## Simple Deployment
 
-- Docker and Docker Compose
-- A MySQL database
+Pulse Signage ships with a Docker Compose stack for the published image:
 
-## First-Time Setup
+- Published-image stack: `docker compose -f docker-compose.yml up -d`
 
-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.
+Use this stack when you want to run the tagged image instead of building from source.
+
+## Environment File
+
+The compose files read from a root `.env` file. Start by copying `.env.example` to `.env`, then adjust the values for your setup.
+
+The variables are split by who uses them:
+
+Shared across the stack:
+
+- `PULSE_SIGNAGE_IMAGE`
+- `PULSE_SIGNAGE_SHARED_SECRET`
+
+Web container:
+
+- `SESSION_MAX_AGE_DAYS`
+- `DEFAULT_ADMIN_USERNAME`
+- `DEFAULT_ADMIN_NAME`
+- `DEFAULT_ADMIN_PASSWORD`
+- `PASSWORD_HASH_ITERATIONS`
+
+Player container:
+
+- `PLAYER_PUBLIC_BASE_URL`
+- `PLAYER_INTERNAL_BASE_URL`
+
+MySQL container:
+
+- `DB_HOST`
+- `DB_PORT`
+- `DB_NAME`
+- `DB_USER`
+- `DB_PASSWORD`
+- `MYSQL_ROOT_PASSWORD`
+
+`DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, and `DB_PASSWORD` are shared in practice because both app containers talk to the same database service.
+
+`PLAYER_INTERNAL_BASE_URL` is used by the web side for server-to-player calls, while `PLAYER_PUBLIC_BASE_URL` is used for browser-facing player links.
+
+## First-Time Use
+
+The first startup seeds a default admin account if the database is empty.
 
 - 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.
+## In Practice
 
-You can change the initial admin credentials with these optional environment variables:
+Pulse Signage is designed to feel focused and reliable rather than heavy or noisy. It works well when you want a clean internal signage system for offices, venues, dashboards, or any environment where screens need to stay up to date without a lot of manual effort.
 
-- `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`
-- `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](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](docs/schema.md). It summarizes the current tables created at startup.
-
-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.
+The player and admin pieces stay linked, so changes made in the dashboard can flow out to screens quickly and consistently.