98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# 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](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
|
|
|
|
- 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](.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. |