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:

# 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:

# 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:

# 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:

# 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)