454 lines
16 KiB
Markdown
454 lines
16 KiB
Markdown
# Infoscreen 2025
|
||
|
||
[](https://www.docker.com/)
|
||
[](https://reactjs.org/)
|
||
[](https://flask.palletsprojects.com/)
|
||
[](https://mariadb.org/)
|
||
[](https://mosquitto.org/)
|
||
|
||
A comprehensive multi-service digital signage solution for educational institutions, featuring client management, event scheduling, presentation conversion, and real-time MQTT communication.
|
||
|
||
## 🏗️ Architecture Overview
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ Dashboard │ │ API Server │ │ Listener │
|
||
│ (React/Vite) │◄──►│ (Flask) │◄──►│ (MQTT Client) │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ MariaDB │ │
|
||
│ │ (Database) │ │
|
||
│ └─────────────────┘ │
|
||
│ │
|
||
└────────────────────┬───────────────────────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ MQTT Broker │
|
||
│ (Mosquitto) │
|
||
└─────────────────┘
|
||
│
|
||
┌────────────────────┼────────────────────┐
|
||
▼ ▼ ▼
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ Scheduler │ │ Worker │ │ Infoscreen │
|
||
│ (Events) │ │ (Conversions) │ │ Clients │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
## 🌟 Key Features
|
||
|
||
### 📊 **Dashboard Management**
|
||
- Modern React-based web interface with Syncfusion components
|
||
- Real-time client monitoring and group management
|
||
- Event scheduling with academic period support
|
||
- Media management with presentation conversion
|
||
- Holiday calendar integration
|
||
|
||
### 🎯 **Event System**
|
||
- **Presentations**: PowerPoint/LibreOffice → PDF conversion via Gotenberg
|
||
- **Websites**: URL-based content display
|
||
- **Videos**: Media file streaming
|
||
- **Messages**: Text announcements
|
||
- **WebUntis**: Educational schedule integration
|
||
|
||
### 🏫 **Academic Period Management**
|
||
- Support for school years, semesters, and trimesters
|
||
- Austrian school system integration
|
||
- Holiday calendar synchronization
|
||
- Period-based event organization
|
||
|
||
### 📡 **Real-time Communication**
|
||
- MQTT-based client discovery and heartbeat monitoring
|
||
- Retained topics for reliable state synchronization
|
||
- WebSocket support for browser clients
|
||
- Automatic client group assignment
|
||
|
||
### 🔄 **Background Processing**
|
||
- Redis-based job queues for presentation conversion
|
||
- Gotenberg integration for LibreOffice/PowerPoint processing
|
||
- Asynchronous file processing with status tracking
|
||
- RQ (Redis Queue) worker management
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### Prerequisites
|
||
- Docker & Docker Compose
|
||
- Git
|
||
- SSL certificates (for production)
|
||
|
||
### Development Setup
|
||
|
||
1. **Clone the repository**
|
||
```bash
|
||
git clone https://github.com/RobbStarkAustria/infoscreen_2025.git
|
||
cd infoscreen_2025
|
||
```
|
||
|
||
2. **Environment Configuration**
|
||
```bash
|
||
cp .env.example .env
|
||
# Edit .env with your configuration
|
||
```
|
||
|
||
3. **Start the development stack**
|
||
```bash
|
||
make up
|
||
# or: docker compose up -d --build
|
||
```
|
||
|
||
4. **Initialize the database (first run only)**
|
||
```bash
|
||
# One-shot: runs all Alembic migrations, creates default admin/group, and seeds academic periods
|
||
python server/initialize_database.py
|
||
```
|
||
|
||
5. **Access the services**
|
||
- Dashboard: http://localhost:5173
|
||
- API: http://localhost:8000
|
||
- Database: localhost:3306
|
||
- MQTT: localhost:1883 (WebSocket: 9001)
|
||
|
||
### Production Deployment
|
||
|
||
1. **Build and push images**
|
||
```bash
|
||
make build
|
||
make push
|
||
```
|
||
|
||
2. **Deploy on server**
|
||
```bash
|
||
make pull-prod
|
||
make up-prod
|
||
```
|
||
|
||
For detailed deployment instructions, see:
|
||
- [Debian Deployment Guide](deployment-debian.md)
|
||
- [Ubuntu Deployment Guide](deployment-ubuntu.md)
|
||
|
||
## 🛠️ Services
|
||
|
||
### 🖥️ **Dashboard** (`dashboard/`)
|
||
- **Technology**: React 19 + TypeScript + Vite
|
||
- **UI Framework**: Syncfusion components (Material 3 theme)
|
||
- **Styling**: Centralized Syncfusion Material 3 CSS imports in `dashboard/src/main.tsx`
|
||
- **Features**: Responsive design, real-time updates, file management
|
||
- **Port**: 5173 (dev), served via Nginx (prod)
|
||
|
||
### 🔧 **API Server** (`server/`)
|
||
- **Technology**: Flask + SQLAlchemy + Alembic
|
||
- **Database**: MariaDB with timezone-aware timestamps
|
||
- **Features**: RESTful API, file uploads, MQTT integration
|
||
- **Port**: 8000
|
||
- **Health Check**: `/health`
|
||
|
||
### 👂 **Listener** (`listener/`)
|
||
- **Technology**: Python + paho-mqtt
|
||
- **Purpose**: MQTT message processing, client discovery
|
||
- **Features**: Heartbeat monitoring, automatic client registration
|
||
|
||
### ⏰ **Scheduler** (`scheduler/`)
|
||
- **Technology**: Python + SQLAlchemy
|
||
- **Purpose**: Event publishing, group-based content distribution
|
||
- **Features**: Time-based event activation, MQTT publishing
|
||
|
||
### 🔄 **Worker** (Conversion Service)
|
||
- **Technology**: RQ (Redis Queue) + Gotenberg
|
||
- **Purpose**: Background presentation conversion
|
||
- **Features**: PPT/PPTX/ODP → PDF conversion, status tracking
|
||
|
||
### 🗄️ **Database** (MariaDB 11.2)
|
||
- **Features**: Health checks, automatic initialization
|
||
- **Migrations**: Alembic-based schema management
|
||
- **Timezone**: UTC-aware timestamps
|
||
|
||
### 📡 **MQTT Broker** (Eclipse Mosquitto 2.0.21)
|
||
- **Features**: WebSocket support, health monitoring
|
||
- **Topics**:
|
||
- `infoscreen/discovery` - Client registration
|
||
- `infoscreen/{uuid}/heartbeat` - Client alive status
|
||
- `infoscreen/events/{group_id}` - Event distribution
|
||
- `infoscreen/{uuid}/group_id` - Client group assignment
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
infoscreen_2025/
|
||
├── dashboard/ # React frontend
|
||
│ ├── src/ # React components and logic
|
||
│ ├── public/ # Static assets
|
||
│ └── Dockerfile # Production build
|
||
├── server/ # Flask API backend
|
||
│ ├── routes/ # API endpoints
|
||
│ ├── alembic/ # Database migrations
|
||
│ ├── media/ # File storage
|
||
│ ├── initialize_database.py # All-in-one DB initialization (dev)
|
||
│ └── worker.py # Background jobs
|
||
├── listener/ # MQTT listener service
|
||
├── scheduler/ # Event scheduling service
|
||
├── models/ # Shared database models
|
||
├── mosquitto/ # MQTT broker configuration
|
||
├── certs/ # SSL certificates
|
||
├── docker-compose.yml # Development setup
|
||
├── docker-compose.prod.yml # Production setup
|
||
└── Makefile # Development shortcuts
|
||
```
|
||
|
||
## 🔧 Development
|
||
|
||
### Available Commands
|
||
|
||
```bash
|
||
# Development
|
||
make up # Start dev stack
|
||
make down # Stop dev stack
|
||
make logs # View all logs
|
||
make logs-server # View specific service logs
|
||
|
||
# Building & Deployment
|
||
make build # Build all images
|
||
make push # Push to registry
|
||
make pull-prod # Pull production images
|
||
make up-prod # Start production stack
|
||
|
||
# Maintenance
|
||
make health # Health checks
|
||
make fix-perms # Fix file permissions
|
||
```
|
||
|
||
### Database Management
|
||
|
||
```bash
|
||
# One-shot initialization (schema + defaults + academic periods)
|
||
python server/initialize_database.py
|
||
|
||
# Access database directly
|
||
docker exec -it infoscreen-db mysql -u${DB_USER} -p${DB_PASSWORD} ${DB_NAME}
|
||
|
||
# Run migrations
|
||
docker exec -it infoscreen-api alembic upgrade head
|
||
|
||
# Initialize academic periods (Austrian school system)
|
||
docker exec -it infoscreen-api python init_academic_periods.py
|
||
```
|
||
|
||
### MQTT Testing
|
||
|
||
```bash
|
||
# Subscribe to all topics
|
||
mosquitto_sub -h localhost -t "infoscreen/#" -v
|
||
|
||
# Publish test message
|
||
mosquitto_pub -h localhost -t "infoscreen/test" -m "Hello World"
|
||
|
||
# Monitor client heartbeats
|
||
mosquitto_sub -h localhost -t "infoscreen/+/heartbeat" -v
|
||
```
|
||
|
||
## 🌐 API Endpoints
|
||
|
||
### Core Resources
|
||
- `GET /api/clients` - List all registered clients
|
||
- `PUT /api/clients/{uuid}/group` - Assign client to group
|
||
- `GET /api/groups` - List client groups with alive status
|
||
- `GET /api/events` - List events with filtering
|
||
- `POST /api/events` - Create new event
|
||
- `GET /api/academic_periods` - List academic periods
|
||
- `POST /api/academic_periods/active` - Set active period
|
||
|
||
### File Management
|
||
- `POST /api/files` - Upload media files
|
||
- `GET /api/files/{path}` - Download files
|
||
- `GET /api/files/converted/{path}` - Download converted PDFs
|
||
- `POST /api/conversions/{media_id}/pdf` - Request conversion
|
||
- `GET /api/conversions/{media_id}/status` - Check conversion status
|
||
|
||
### Health & Monitoring
|
||
- `GET /health` - Service health check
|
||
- `GET /api/screenshots/{uuid}.jpg` - Client screenshots
|
||
|
||
## 🎨 Frontend Features
|
||
|
||
### Syncfusion Components Used (Material 3)
|
||
- **Schedule**: Event calendar with drag-drop support
|
||
- **Grid**: Data tables with filtering and sorting
|
||
- **DropDownList**: Group and period selectors
|
||
- **FileManager**: Media upload and organization
|
||
- **Kanban**: Task management views
|
||
- **Notifications**: Toast messages and alerts
|
||
- **Pager**: Used on Programinfo changelog for pagination
|
||
- **Cards (layouts)**: Programinfo sections styled with Syncfusion card classes
|
||
|
||
### Pages Overview
|
||
- **Dashboard**: System overview and statistics
|
||
- **Clients**: Device management and monitoring
|
||
- **Groups**: Client group organization
|
||
- **Events**: Schedule management
|
||
- **Media**: File upload and conversion
|
||
- **Settings**: System configuration
|
||
- **Holidays**: Academic calendar management
|
||
- **Program info**: Version, build info, tech stack and paginated changelog (reads `dashboard/public/program-info.json`)
|
||
|
||
## 🔒 Security & Authentication
|
||
|
||
- **Environment Variables**: Sensitive data via `.env`
|
||
- **SSL/TLS**: HTTPS support with custom certificates
|
||
- **MQTT Security**: Username/password authentication
|
||
- **Database**: Parameterized queries, connection pooling
|
||
- **File Uploads**: Type validation, size limits
|
||
- **CORS**: Configured for production deployment
|
||
|
||
## 📊 Monitoring & Logging
|
||
|
||
### Health Checks
|
||
All services include Docker health checks:
|
||
- API: HTTP endpoint monitoring
|
||
- Database: Connection and initialization status
|
||
- MQTT: Pub/sub functionality test
|
||
- Dashboard: Nginx availability
|
||
|
||
### Logging Strategy
|
||
- **Development**: Docker Compose logs with service prefixes
|
||
- **Production**: Centralized logging via Docker log drivers
|
||
- **MQTT**: Message-level debugging available
|
||
- **Database**: Query logging in development mode
|
||
|
||
## 🌍 Deployment Options
|
||
|
||
### Development
|
||
- **Hot Reload**: Vite dev server + Flask debug mode
|
||
- **Volume Mounts**: Live code editing
|
||
- **Debug Ports**: Python debugger support (port 5678)
|
||
- **Local Certificates**: Self-signed SSL for testing
|
||
|
||
### Production
|
||
- **Optimized Builds**: Multi-stage Dockerfiles
|
||
- **Reverse Proxy**: Nginx with SSL termination
|
||
- **Health Monitoring**: Comprehensive healthchecks
|
||
- **Registry**: GitHub Container Registry integration
|
||
- **Scaling**: Docker Compose for single-node deployment
|
||
|
||
## 🤝 Contributing
|
||
|
||
1. Fork the repository
|
||
2. Create a feature branch: `git checkout -b feature/amazing-feature`
|
||
3. Commit your changes: `git commit -m 'Add amazing feature'`
|
||
4. Push to the branch: `git push origin feature/amazing-feature`
|
||
5. Open a Pull Request
|
||
|
||
### Development Guidelines
|
||
- Follow existing code patterns and naming conventions
|
||
- Add appropriate tests for new features
|
||
- Update documentation for API changes
|
||
- Use TypeScript for frontend development
|
||
- Follow Python PEP 8 for backend code
|
||
|
||
## 📋 Requirements
|
||
|
||
### System Requirements
|
||
- **CPU**: 2+ cores recommended
|
||
- **RAM**: 4GB minimum, 8GB recommended
|
||
- **Storage**: 20GB+ for media files and database
|
||
- **Network**: Reliable internet for client communication
|
||
|
||
### Software Dependencies
|
||
- Docker 24.0+
|
||
- Docker Compose 2.0+
|
||
- Git 2.30+
|
||
- Modern web browser (Chrome, Firefox, Safari, Edge)
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Common Issues
|
||
|
||
**Services won't start**
|
||
```bash
|
||
# Check service health
|
||
make health
|
||
|
||
# View specific service logs
|
||
make logs-server
|
||
make logs-db
|
||
```
|
||
|
||
**Database connection errors**
|
||
```bash
|
||
# Verify database is running
|
||
docker exec -it infoscreen-db mysqladmin ping
|
||
|
||
# Check credentials in .env file
|
||
# Restart dependent services
|
||
```
|
||
|
||
**MQTT communication issues**
|
||
```bash
|
||
# Test MQTT broker
|
||
mosquitto_pub -h localhost -t test -m "hello"
|
||
|
||
# Check client certificates and credentials
|
||
# Verify firewall settings for ports 1883/9001
|
||
```
|
||
|
||
**File conversion problems**
|
||
```bash
|
||
# Check Gotenberg service
|
||
curl http://localhost:3000/health
|
||
|
||
# Monitor worker logs
|
||
make logs-worker
|
||
|
||
# Check Redis queue status
|
||
docker exec -it infoscreen-redis redis-cli LLEN conversions
|
||
```
|
||
|
||
## 📄 License
|
||
|
||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||
|
||
## 🙏 Acknowledgments
|
||
|
||
- **Syncfusion**: UI components for React dashboard
|
||
- **Eclipse Mosquitto**: MQTT broker implementation
|
||
- **Gotenberg**: Document conversion service
|
||
- **MariaDB**: Reliable database engine
|
||
- **Flask**: Python web framework
|
||
- **React**: Frontend user interface library
|
||
|
||
---
|
||
|
||
For detailed technical documentation, deployment guides, and API specifications, please refer to the additional documentation files in this repository.
|
||
|
||
Notes:
|
||
- Tailwind CSS was removed. Styling is managed via Syncfusion Material 3 theme imports in `dashboard/src/main.tsx`.
|
||
|
||
## 🧭 Changelog Style Guide
|
||
|
||
When adding entries to `dashboard/public/program-info.json` (displayed on the Program info page):
|
||
|
||
- Structure per release
|
||
- `version` (e.g., `2025.1.0-alpha.8`)
|
||
- `date` in `YYYY-MM-DD` (ISO format)
|
||
- `changes`: array of short bullet strings
|
||
|
||
- Categories (Keep a Changelog inspired)
|
||
- Prefer starting bullets with an implicit category or an emoji, e.g.:
|
||
- Added (🆕/✨), Changed (🔧/🛠️), Fixed (🐛/✅), Removed (🗑️), Security (🔒), Deprecated (⚠️)
|
||
|
||
- Writing rules
|
||
- Keep bullets concise (ideally one line) and user-facing; avoid internal IDs or jargon
|
||
- Put the affected area first when helpful (e.g., “UI: …”, “API: …”, “Scheduler: …”)
|
||
- Highlight breaking changes with “BREAKING:”
|
||
- Prefer German wording consistently; dates are localized at runtime for display
|
||
|
||
- Ordering and size
|
||
- Newest release first in the array
|
||
- Aim for ≤ 8–10 bullets per release; group or summarize if longer
|
||
|
||
- JSON hygiene
|
||
- Valid JSON only (no trailing commas); escape quotes as needed
|
||
- One release object per version; do not modify historical entries unless to correct typos
|
||
|
||
The Program info page paginates older entries (default page size 5). Keep highlights at the top of each release for scanability.
|