From 877ff3f896cd95ae7d0e30dda7c71ae37b3a0bc0 Mon Sep 17 00:00:00 2001
From: Mark Rapson <git@lzstealth.com>
Date: Mon, 13 Jul 2026 21:49:00 +0100
Subject: [PATCH] Add Readme

---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6bd0abf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# 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
+
+## 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
+docker-compose up --build
+```
+
+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.
+
+## 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.
\ No newline at end of file