digiserver-v2/old_code_documentation/OPTIONAL_DEPENDENCIES.md

# Optional Dependencies Guide

DigiServer v2 uses an optimized dependency installation strategy to minimize Docker image size while maintaining full functionality.

## Overview

The base Docker image (~400MB) includes only essential dependencies:
- **Poppler Utils** - PDF to image conversion
- **FFmpeg** - Video processing and validation
- **Python 3.13** - Application runtime

Optional dependencies can be installed on-demand:
- **LibreOffice** (~500MB) - PowerPoint (PPTX/PPT) to image conversion

## Why Optional Dependencies?

By excluding LibreOffice from the base image, we reduce:
- **Initial image size**: From ~900MB to ~400MB (56% reduction)
- **Download time**: Faster deployments
- **Storage requirements**: Lower disk usage on hosts

Users who don't need PowerPoint conversion benefit from a smaller, faster image.

## Installation Methods

### 1. Web UI (Recommended)

The easiest way to install LibreOffice:

1. Log in to DigiServer admin panel
2. Navigate to **Admin Panel** → **System Dependencies**
3. Click **"Install LibreOffice"** button
4. Wait 2-5 minutes for installation
5. Refresh the page to verify installation

The web interface provides:
- Real-time installation status
- Version verification
- Error reporting
- No terminal access needed

### 2. Docker Exec (Manual)

For Docker deployments, use `docker exec`:

```bash
# Enter the container
docker exec -it digiserver bash

# Run the installation script
sudo /app/install_libreoffice.sh

# Verify installation
libreoffice --version
```

### 3. Direct Installation (Non-Docker)

For bare-metal or VM deployments:

```bash
# Make script executable (if not already)
chmod +x /srv/digiserver-v2/install_libreoffice.sh

# Run the installation script
sudo /srv/digiserver-v2/install_libreoffice.sh

# Verify installation
libreoffice --version
```

## Checking Dependency Status

### Web Interface

Navigate to **Admin Panel** → **System Dependencies** to see:
- ✅ LibreOffice: Installed or ❌ Not installed
- ✅ Poppler Utils: Installed (always present)
- ✅ FFmpeg: Installed (always present)

### Command Line

Check individual dependencies:

```bash
# LibreOffice
libreoffice --version

# Poppler
pdftoppm -v

# FFmpeg
ffmpeg -version
```

## File Type Support Matrix

| File Type | Required Dependency | Status |
|-----------|-------------------|---------|
| **Images** (JPG, PNG, GIF) | None | Always supported |
| **PDF** | Poppler Utils | Always available |
| **Videos** (MP4, AVI, MOV) | FFmpeg | Always available |
| **PowerPoint** (PPTX, PPT) | LibreOffice | Optional install |

## Upload Behavior

### Without LibreOffice

When you try to upload a PowerPoint file without LibreOffice:
- Upload will be **rejected**
- Error message: *"LibreOffice is not installed. Please install it from the Admin Panel → System Dependencies to upload PowerPoint files."*
- Other file types (PDF, images, videos) work normally

### With LibreOffice

After installation:
- PowerPoint files are converted to high-quality PNG images
- Each slide becomes a separate media item
- Slides maintain aspect ratio and resolution
- Original PPTX file is deleted after conversion

## Technical Details

### Installation Script

The `install_libreoffice.sh` script:
1. Checks for root/sudo privileges
2. Verifies if LibreOffice is already installed
3. Updates apt package cache
4. Installs `libreoffice` and `libreoffice-impress`
5. Verifies successful installation
6. Reports version and status

### Docker Implementation

The Dockerfile includes:
- Sudo access for `appuser` to run installation script
- Script permissions set during build
- No LibreOffice in base layers (smaller image)

### Security Considerations

- Installation requires sudo/root access
- In Docker, `appuser` has limited sudo rights (only for installation script)
- Installation script validates LibreOffice binary after install
- No external downloads except from official apt repositories

## Installation Time

Typical installation times:
- **Fast network** (100+ Mbps): 2-3 minutes
- **Average network** (10-100 Mbps): 3-5 minutes
- **Slow network** (<10 Mbps): 5-10 minutes

The installation downloads approximately 450-500MB of packages.

## Troubleshooting

### Installation Fails

**Error**: "Permission denied"
- **Solution**: Ensure script has execute permissions (`chmod +x`)
- **Docker**: Check sudoers configuration in Dockerfile

**Error**: "Unable to locate package"
- **Solution**: Run `sudo apt-get update` first
- **Docker**: Rebuild image with fresh apt cache

### Installation Hangs

- Check internet connectivity
- Verify apt repositories are accessible
- In Docker, check container has network access
- Increase timeout if on slow connection

### Verification Fails

**Symptom**: Installation completes but LibreOffice not found
- **Solution**: Check LibreOffice was installed to expected path
- Run: `which libreoffice` to locate binary
- Verify with: `libreoffice --version`

### Upload Still Fails After Installation

1. Verify installation: Admin Panel → System Dependencies
2. Check server logs for conversion errors
3. Restart application: `docker restart digiserver` (Docker) or restart Flask
4. Try uploading a simple PPTX file to test

## Uninstallation

To remove LibreOffice and reclaim space:

```bash
# In container or host
sudo apt-get remove --purge libreoffice libreoffice-impress
sudo apt-get autoremove
sudo apt-get clean
```

This frees approximately 500MB of disk space.

## Production Recommendations

### When to Install LibreOffice

Install LibreOffice if:
- Users need to upload PowerPoint presentations
- You have >1GB free disk space
- Network bandwidth supports 500MB download

### When to Skip LibreOffice

Skip LibreOffice if:
- Only using PDF, images, and videos
- Disk space is constrained (<2GB)
- Want minimal installation footprint
- Can convert PPTX to PDF externally

### Multi-Container Deployments

For multiple instances:
- **Option A**: Create custom image with LibreOffice pre-installed
- **Option B**: Install on each container individually
- **Option C**: Use shared volume for LibreOffice binaries

## FAQ

**Q: Will removing LibreOffice break existing media?**  
A: No, converted slides remain as PNG images after conversion.

**Q: Can I pre-install LibreOffice in the Docker image?**  
A: Yes, uncomment the `libreoffice` line in Dockerfile and rebuild.

**Q: How much space does LibreOffice use?**  
A: Approximately 450-500MB installed.

**Q: Does LibreOffice run during conversion?**  
A: Yes, in headless mode. It converts slides to PNG without GUI.

**Q: Can I use other presentation converters?**  
A: The code currently only supports LibreOffice. Custom converters require code changes.

**Q: Is LibreOffice safe for production?**  
A: Yes, LibreOffice is widely used in production environments for document conversion.

## Support

For issues with optional dependencies:
1. Check the **System Dependencies** page in Admin Panel
2. Review server logs: `docker logs digiserver`
3. Verify system requirements (disk space, memory)
4. Consult DOCKER.md for container-specific guidance

## Version History

- **v2.0**: Introduced optional LibreOffice installation
- **v1.0**: LibreOffice included in base image (larger size)