digiserver-v2/old_code_documentation/README.md

# DigiServer v2

Digital Signage Management System - A modern Flask-based application for managing content playlists across multiple display screens.

## Features

- 📺 **Multi-Player Management** - Control multiple display screens from one interface
- 🎬 **Playlist System** - Create and manage content playlists with drag-and-drop reordering
- 📁 **Media Library** - Upload and organize images, videos, PDFs, and presentations
- 📄 **PDF to Image Conversion** - Automatic conversion of PDF pages to Full HD images (300 DPI)
- 📊 **PowerPoint Support** - Convert PPTX slides to images automatically (optional LibreOffice install)
- 🖼️ **Live Preview** - Real-time content preview for each player
- ⚡ **Real-time Updates** - Players automatically sync with playlist changes
- 🌓 **Dark Mode** - Full dark mode support across all interfaces
- 🗑️ **Media Management** - Clean up unused media files with leftover media manager
- 🔧 **Optional Dependencies** - Install LibreOffice on-demand to reduce base image size by 56%
- 🔒 **User Authentication** - Secure admin access with role-based permissions

## Quick Start

### Option 1: Docker (Recommended)

```bash
# Quick start with Docker
./docker-start.sh
```

Access at: `http://localhost:5000`

Default credentials: `admin` / `admin123`

See [DOCKER.md](DOCKER.md) for detailed Docker documentation.

### Option 2: Manual Installation

#### Prerequisites

- Python 3.13+
- Poppler Utils (for PDF conversion) - **Required**
- FFmpeg (for video processing) - **Required**
- LibreOffice (for PPTX conversion) - **Optional** (can be installed via Admin Panel)

#### Installation

```bash
# Install required system dependencies (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install -y poppler-utils ffmpeg libmagic1

# Optional: Install LibreOffice for PowerPoint conversion
# OR install later via Admin Panel → System Dependencies
sudo apt-get install -y libreoffice

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Initialize database
python -c "
from app.app import create_app
from app.extensions import db, bcrypt
from app.models import User

app = create_app()
with app.app_context():
    db.create_all()
    hashed = bcrypt.generate_password_hash('admin123').decode('utf-8')
    admin = User(username='admin', password=hashed, role='admin')
    db.session.add(admin)
    db.session.commit()
    print('Admin user created')
"

# Run development server
./run_dev.sh
```

Access at: `http://localhost:5000`

## Deployment

### Docker Deployment

```bash
# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down
```

### Production Deployment

For production, use:
- Gunicorn or uWSGI as WSGI server
- Nginx as reverse proxy
- Redis for caching (optional)
- PostgreSQL for larger deployments (optional)

See [DOCKER.md](DOCKER.md) for detailed deployment instructions.

## Usage

### 1. Create a Playlist

1. Navigate to **Playlist Management**
2. Fill in playlist details (name, orientation, description)
3. Click **Create Playlist**

### 2. Upload Media

1. Go to **Upload Media** page
2. Select files (images, videos, PDFs, PPTX)
3. Choose media type and duration
4. Select target playlist (optional)
5. Click **Upload**

**Supported Formats:**
- Images: JPG, PNG, GIF, BMP, WEBP
- Videos: MP4, AVI, MOV, MKV, WEBM
- Documents: PDF, PPT, PPTX

### 3. Manage Playlists

1. Open playlist management
2. Drag and drop to reorder content
3. Edit duration for each item
4. Remove unwanted items
5. Changes sync automatically to players

### 4. Assign to Players

1. Go to **Player Assignments**
2. Select playlist from dropdown for each player
3. View live preview to verify content

### 5. Clean Up Media

1. Navigate to **Admin** → **Manage Leftover Media**
2. Review unused files
3. Delete individual files or bulk delete by type

## Configuration

### Environment Variables

Create a `.env` file:

```env
FLASK_ENV=production
SECRET_KEY=your-random-secret-key
DATABASE_URL=sqlite:///instance/digiserver.db
```

### Upload Settings

Edit `app/config.py` to adjust:
- Upload folder location
- Maximum file size
- Allowed file extensions

## Project Structure

```
digiserver-v2/
├── app/
│   ├── blueprints/      # Route handlers
│   │   ├── admin.py     # Admin panel routes
│   │   ├── content.py   # Content management
│   │   ├── playlist.py  # Playlist operations
│   │   └── players.py   # Player management
│   ├── models/          # Database models
│   ├── templates/       # HTML templates
│   ├── static/          # CSS, JS, uploads
│   └── utils/           # Helper functions
├── instance/            # Database storage
├── Dockerfile           # Docker configuration
├── docker-compose.yml   # Docker Compose config
└── requirements.txt     # Python dependencies
```

## API Endpoints

### Player API
- `GET /api/playlist/<player_id>` - Get player playlist
- `POST /api/players/<player_id>/heartbeat` - Send heartbeat

### Admin API
- `POST /playlist/<player_id>/update-duration/<content_id>` - Update content duration
- `POST /playlist/<player_id>/reorder` - Reorder playlist items

## Troubleshooting

### PDF Conversion Fails
Ensure poppler-utils is installed:
```bash
sudo apt-get install poppler-utils
```

### PPTX Conversion Fails
**Method 1: Via Web UI (Recommended)**
1. Go to Admin Panel → System Dependencies
2. Click "Install LibreOffice"
3. Wait 2-5 minutes for installation

**Method 2: Manual Install**
```bash
sudo apt-get install libreoffice
# OR use the provided script
sudo ./install_libreoffice.sh
```

See [OPTIONAL_DEPENDENCIES.md](OPTIONAL_DEPENDENCIES.md) for details.

### Upload Fails
Check folder permissions:
```bash
chmod -R 755 app/static/uploads
```

### Database Issues
Reset database:
```bash
rm instance/*.db
# Then reinitialize (see Installation)
```

## Development

### Running Tests
```bash
pytest
```

### Code Formatting
```bash
black app/
flake8 app/
```

### Database Migrations
```bash
flask db migrate -m "Description"
flask db upgrade
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

This project is proprietary software. All rights reserved.

## Documentation

- [DOCKER.md](DOCKER.md) - Docker deployment guide
- [OPTIONAL_DEPENDENCIES.md](OPTIONAL_DEPENDENCIES.md) - Optional dependency installation
- [PROGRESS.md](PROGRESS.md) - Development progress tracker
- [KIVY_PLAYER_COMPATIBILITY.md](KIVY_PLAYER_COMPATIBILITY.md) - Player integration guide

## Support

For issues and questions:
- Check [DOCKER.md](DOCKER.md) for deployment help
- Review [OPTIONAL_DEPENDENCIES.md](OPTIONAL_DEPENDENCIES.md) for LibreOffice setup
- Review troubleshooting section
- Check application logs

## Version History

- **v2.1** - Optional LibreOffice installation
  - Reduced base Docker image by 56% (~900MB → ~400MB)
  - On-demand LibreOffice installation via Admin Panel
  - System Dependencies management page
  - Enhanced error messages for PPTX without LibreOffice
  
- **v2.0** - Complete rewrite with playlist-centric architecture
  - PDF to image conversion (300 DPI)
  - PPTX slide conversion
  - Leftover media management
  - Enhanced dark mode
  - Duration editing for all content types

---

Built with ❤️ using Flask, SQLAlchemy, and modern web technologies