Initial commit - copied workspace after database cleanup
This commit is contained in:
RobbStarkAustria
407
README.md
Normal file
407
README.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# 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 <repository-url>
|
||||
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. **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 + Tailwind CSS
|
||||
- **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
|
||||
│ └── 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
|
||||
# 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
|
||||
- **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
|
||||
|
||||
### 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
|
||||
|
||||
## 🔒 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.
|
||||
Reference in New Issue
Block a user