v1.0.0: Full README with deployment guide, terminology, and usage
This commit is contained in:
@@ -1,3 +1,141 @@
|
|||||||
# ScratchingPost
|
# Scratching Post — Sunbeam Digital Signage
|
||||||
|
|
||||||
Sunbeam Digital Signage — A self-hosted notice board system for IIS. WYSIWYG slides, embeds, ICS calendars, device playlists.
|
A self-hosted digital notice board / signage system built on ASP.NET Core 8, designed for IIS on Windows Server 2019/2022.
|
||||||
|
|
||||||
|
## Terminology
|
||||||
|
|
||||||
|
| Component | Name | Description |
|
||||||
|
|-----------|------|-------------|
|
||||||
|
| Individual slide | **Meow** | A single content slide — WYSIWYG, embed, or calendar |
|
||||||
|
| Slide collection | **PURR** | Persistent User Requests and Reminders — a device playlist |
|
||||||
|
| Priority slide | **ASK** | Attention Seeking Kitty — overrides collection order *(planned)* |
|
||||||
|
| Display node | **Kitten** | A device that plays a playlist of Meows |
|
||||||
|
| Backend | **Scratching Post** | The admin panel where all content is managed |
|
||||||
|
| Framework | **Sunbeam** | The underlying system powering everything |
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **WYSIWYG Editor** — TinyMCE with image upload, tables, rich text
|
||||||
|
- **Embed Web Content** — iframe any URL as a slide
|
||||||
|
- **ICS Calendar** — display upcoming events from any .ics feed
|
||||||
|
- **Device Playlists** — assign slides to specific devices with individual durations
|
||||||
|
- **Per-Device Resolution** — configure display resolution per device
|
||||||
|
- **URL-Based Devices** — access displays via `http://server/frontofhouse`, `http://server/staffroom`
|
||||||
|
- **Drag-and-Drop Playlist** — reorder slides in the admin
|
||||||
|
- **Live Updates** — display polls for changes every 30 seconds
|
||||||
|
- **Full-Screen Display** — hidden cursor, clock overlay, progress bar
|
||||||
|
- **Smooth Transitions** — fade or slide transitions
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Windows Server 2019 or 2022
|
||||||
|
- IIS with ASP.NET Core Hosting Bundle
|
||||||
|
- .NET 8 SDK (for building) / .NET 8 Runtime (for hosting)
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### 1. Install Prerequisites
|
||||||
|
|
||||||
|
Download and install:
|
||||||
|
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
|
||||||
|
- [ASP.NET Core Hosting Bundle](https://dotnet.microsoft.com/download/dotnet/8.0) (under Hosting Bundle)
|
||||||
|
|
||||||
|
### 2. Build
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
cd ScratchingPost
|
||||||
|
dotnet restore
|
||||||
|
dotnet publish -c Release -o ./publish
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Deploy to IIS
|
||||||
|
|
||||||
|
1. Open **IIS Manager**
|
||||||
|
2. Create a new **Site** (e.g. ScratchingPost)
|
||||||
|
3. Set the **physical path** to the `publish` folder
|
||||||
|
4. Set the **binding** (e.g. port 80, or a hostname like `sign.local`)
|
||||||
|
5. Set the **Application Pool** to **No Managed Code** (the Hosting Bundle handles .NET)
|
||||||
|
6. Ensure the App Pool identity has **write access** to the publish folder (for SQLite DB and uploads)
|
||||||
|
|
||||||
|
### 4. First Run
|
||||||
|
|
||||||
|
The SQLite database (`noticeboard.db`) is created automatically on first start with two demo devices seeded:
|
||||||
|
- **Front of House** at `http://server/frontofhouse`
|
||||||
|
- **Staff Room** at `http://server/staffroom`
|
||||||
|
|
||||||
|
### 5. Access
|
||||||
|
|
||||||
|
| URL | Purpose |
|
||||||
|
|-----|---------|
|
||||||
|
| `http://server/admin` | Scratching Post admin panel |
|
||||||
|
| `http://server/admin/slides` | Manage Meows (slides) |
|
||||||
|
| `http://server/admin/devices` | Manage Kittens (devices) |
|
||||||
|
| `http://server/frontofhouse` | Front of House display |
|
||||||
|
| `http://server/staffroom` | Staff Room display |
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Edit `appsettings.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"MaxUploadSizeMB": 20
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
1. **Create Meows** (slides) — use the WYSIWYG editor for rich content, embed external URLs, or point to an ICS calendar feed
|
||||||
|
2. **Create Kittens** (devices) — give each a name, URL slug, and display resolution
|
||||||
|
3. **Build PURRs** (playlists) — assign Meows to Kittens with individual durations and drag-and-drop ordering
|
||||||
|
4. **Display** — point a browser at `http://server/{slug}` and it runs full-screen with smooth transitions
|
||||||
|
|
||||||
|
The display page polls for changes every 30 seconds, so updates appear on devices without restarting.
|
||||||
|
|
||||||
|
## Display Controls
|
||||||
|
|
||||||
|
Keyboard shortcuts on display pages (useful during setup):
|
||||||
|
|
||||||
|
| Key | Action |
|
||||||
|
|-----|--------|
|
||||||
|
| Right Arrow or Space | Skip to next slide |
|
||||||
|
| Left Arrow | Go to previous slide |
|
||||||
|
| F or F11 | Toggle fullscreen |
|
||||||
|
| C | Toggle cursor visibility |
|
||||||
|
|
||||||
|
## Data Storage
|
||||||
|
|
||||||
|
- **Database**: SQLite (`noticeboard.db`) — created automatically, zero config
|
||||||
|
- **Uploads**: `wwwroot/uploads/` — images uploaded via TinyMCE or the file upload API
|
||||||
|
- Both need write permissions for the IIS App Pool identity
|
||||||
|
|
||||||
|
## TinyMCE Note
|
||||||
|
|
||||||
|
The WYSIWYG editor uses TinyMCE CDN with `no-api-key`. This shows a small notification banner. For production, register for a free TinyMCE API key at [tiny.cloud](https://www.tiny.cloud/) and replace `no-api-key` in `Views/Slides/Create.cshtml` and `Edit.cshtml`.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
ScratchingPost/
|
||||||
|
├── Controllers/ # MVC controllers
|
||||||
|
│ ├── AdminController # Dashboard
|
||||||
|
│ ├── SlidesController # Meow CRUD
|
||||||
|
│ ├── DevicesController # Kitten CRUD + Playlist management
|
||||||
|
│ ├── DisplayController # Device display + playlist API
|
||||||
|
│ └── ApiController # Image upload, ICS parsing
|
||||||
|
├── Data/ # EF Core DbContext + seed data
|
||||||
|
├── Models/ # Slide, Device, DeviceSlide
|
||||||
|
├── Routing/ # DeviceSlugConstraint
|
||||||
|
├── Views/ # Razor views (Admin, Slides, Devices, Display)
|
||||||
|
├── wwwroot/ # Static files
|
||||||
|
│ ├── css/ # admin.css, display.css
|
||||||
|
│ ├── js/ # admin.js, display.js (Sunbeam engine)
|
||||||
|
│ └── uploads/ # User-uploaded images
|
||||||
|
├── appsettings.json # Configuration
|
||||||
|
├── web.config # IIS configuration
|
||||||
|
└── NoticeBoard.csproj # Project file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
- **v1.0.0** — Initial release: WYSIWYG slides, embed, ICS calendar, device playlists, drag-and-drop ordering, live polling, IIS-ready deployment
|
||||||
|
|||||||
Reference in New Issue
Block a user