digiserver/README.md

DigiServer - Digital Signage Management Platform

DigiServer is a comprehensive digital signage management platform built with Flask. It allows you to manage digital displays, create playlists, organize content into groups, and control multiple players from a centralized dashboard.

🚀 Features

• Multi-Player Management: Control multiple digital signage players from a single dashboard
• Group Management: Organize players into groups for synchronized content
• Content Management: Upload and manage various media types (images, videos, PDFs, PowerPoint presentations)
• Real-time Updates: Players automatically sync with the latest content
• User Management: Admin and user role-based access control
• Orientation Support: Configure display orientation (Landscape/Portrait) per player and group
• API Integration: RESTful API for player authentication and playlist retrieval
• Docker Support: Easy deployment with Docker containers

📋 Requirements

• Docker and Docker Compose
• Python 3.11+ (if running without Docker)
• FFmpeg (for video processing)
• LibreOffice (for document conversion)

📁 Project Structure

digiserver/
├── app/                    # Application code
│   ├── models/            # Database models
│   ├── templates/         # HTML templates
│   ├── utils/            # Utility functions
│   ├── app.py            # Main Flask application
│   ├── extensions.py     # Flask extensions
│   ├── requirements.txt  # Python dependencies
│   └── entrypoint.sh     # Container entry point
├── data/                  # Persistent data (created on first run)
│   ├── instance/         # Database files
│   ├── uploads/          # Media uploads
│   └── resurse/          # System resources (logos, etc.)
├── docker-compose.yml    # Docker Compose configuration
├── Dockerfile           # Docker image definition
└── README.md           # This file

🐳 Quick Start with Docker

Automated Deployment (Recommended)

1. Clone the repository

   git clone <repository-url>
   cd digiserver
   

2. Deploy with automated script

   ./deploy-docker.sh
   

   This script will:

   • Check Docker requirements
   • Build the DigiServer image
   • Create necessary data directories
   • Start the containers
   • Display access information

3. Access the application

   • Open your browser and navigate to http://localhost:8880
   • Default admin credentials:
     • Username: admin
     • Password: Initial01!

Manual Docker Commands

Alternatively, you can use Docker commands directly:

# Build and start
docker compose up -d

# Stop
docker compose down

# View logs
docker compose logs -f

# Check status
docker compose ps

Clean Up

To completely remove DigiServer containers and images:

./cleanup-docker.sh

🔧 Configuration

Environment Variables

You can customize the application by modifying the environment variables in docker-compose.yml:

• ADMIN_USER: Default admin username (default: admin)
• ADMIN_PASSWORD: Default admin password (default: Initial01!)
• SECRET_KEY: Flask secret key for session security
• FLASK_APP: Flask application entry point
• FLASK_RUN_HOST: Host to bind the Flask application

Data Persistence

All persistent data is stored in the data/ folder:

• data/instance/: SQLite database files
• data/uploads/: Uploaded media files
• data/resurse/: System resources (logo, login images)

This folder will be created automatically on first run and persists between container restarts.

💻 Manual Installation (Development)

If you prefer to run without Docker:

1. Install system dependencies

   # Ubuntu/Debian
   sudo apt-get update
   sudo apt-get install python3.11 python3-pip libreoffice ffmpeg
   
   # CentOS/RHEL
   sudo yum install python3.11 python3-pip libreoffice ffmpeg
   

2. Install Python dependencies

   cd app/
   pip install -r requirements.txt
   

3. Run the application

   python app.py
   

🎮 Usage

Managing Players

1. Add a Player: Navigate to the dashboard and click "Add Player"
2. Configure Player: Set username, hostname, passwords, and orientation
3. Upload Content: Upload media files to the player's playlist
4. Player Authentication: Players can authenticate using hostname and password/quickconnect code

Managing Groups

1. Create Group: Group multiple players for synchronized content
2. Assign Players: Add/remove players from groups
3. Upload Group Content: Upload content that will be shared across all players in the group
4. Group Display: View group content in fullscreen mode

Content Types Supported

• Images: JPG, PNG, GIF
• Videos: MP4, AVI, MOV (automatically converted to MP4)
• Documents: PDF (converted to images)
• Presentations: PPTX (converted to images)

🔌 API Endpoints

Player API

• GET /api/playlists?hostname={hostname}&quickconnect_code={code}: Get player playlist
• GET /api/playlist_version?hostname={hostname}&quickconnect_code={code}: Get playlist version
• GET /media/{filename}: Serve media files

Authentication

Players authenticate using:

• Hostname: Unique identifier for the player
• Password: Primary authentication method
• Quickconnect Code: Alternative authentication method

🛠️ Development

Building the Docker Image

docker build -t digiserver:latest .

Running Tests

# Install test dependencies
pip install pytest pytest-flask

# Run tests
pytest

Database Management

The application uses SQLite with Flask-Migrate for database management:

# Initialize database
flask db init

# Create migration
flask db migrate -m "Description of changes"

# Apply migration
flask db upgrade

🔒 Security

• User Authentication: Role-based access control (admin/user)
• Player Authentication: Secure hostname and password-based authentication
• File Upload Security: Secure filename handling and file type validation
• Session Management: Secure session handling with configurable secret key

📊 Monitoring

• Server Logs: View recent server activities from the dashboard
• Health Check: Docker health check endpoint for monitoring
• Content Management: Track content usage and cleanup unused files

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the documentation in the docs/ folder
• Review the application logs for troubleshooting

🔄 Version History

• 1.1.0 (2025-06-29): Added orientation support, improved group management
• 1.0.0: Initial release with basic digital signage functionality

---

Note: Make sure to change the default admin password after first login for security purposes.