# 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`

## Docker Compose

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

- `webui` - the admin app on port `3000`
- `player` - the signage player on port `3001`
- `mysql` - the database on port `3306`

By default, `webui` 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 `uploads` volume for media and a `mysql_data` volume for database persistence.

## 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.