Deploying Gerbera

Introduction

Gerbera is a UPnP (Universal Plug and Play) media server that allows you to stream your digital media through your home network and consume it on a variety of UPnP-compatible devices. Originally forked from MediaTomb, Gerbera has evolved into a modern, actively maintained media server with a clean web interface.

Gerbera automatically scans your media directories, extracts metadata, and serves content to devices like smart TVs, game consoles, streaming boxes, and DLNA-compatible media players. The server supports automatic directory scanning, transcoding, and customizable import scripts.

Key highlights of Gerbera:

• UPnP/DLNA Compatibility: Stream to any UPnP/DLNA compatible device
• Web Interface: Modern, responsive UI for configuration and browsing
• Automatic Scanning: Automatically index new media files
• Metadata Extraction: Extract and display media metadata and artwork
• Transcoding Support: Transcode media for incompatible devices
• JavaScript Scripting: Customize media import with JavaScript
• Container Support: Virtual containers for organizing content
• Multiple Clients: Serve multiple devices simultaneously
• Open Source: Licensed under GPL v2

This guide walks through deploying Gerbera on Klutch.sh using Docker, configuring your media library, and setting up streaming for your devices.

Why Deploy Gerbera on Klutch.sh

Deploying Gerbera on Klutch.sh provides several advantages for media streaming:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gerbera. Push to GitHub, and your media server deploys automatically.

Persistent Storage: Attach persistent volumes for your media library and database. Your content and settings survive redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for the web interface.

GitHub Integration: Connect your configuration repository directly from GitHub for automatic updates.

Scalable Resources: Allocate resources based on your media library size and transcoding needs.

Always-On Availability: Your media server remains accessible 24/7 for streaming.

Prerequisites

Before deploying Gerbera on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Gerbera configuration
• Basic familiarity with Docker and containerization concepts
• Media files ready to stream
• (Optional) UPnP/DLNA compatible devices for playback

Understanding Gerbera Architecture

Gerbera uses a straightforward architecture:

C++ Core: The server is written in C++ for performance and efficient memory usage.

SQLite Database: Media metadata and configuration stored in SQLite for portability.

UPnP/SSDP Stack: Handles device discovery and media serving via UPnP protocol.

Web Interface: Modern web UI for configuration and library browsing.

Transcoding Pipeline: Optional transcoding for format conversion.

Preparing Your Repository

To deploy Gerbera on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

gerbera-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM gerbera/gerbera:latest

# Set user IDs for file permissions
ENV UID=${UID:-1000}
ENV GID=${GID:-1000}

# Create content directory
RUN mkdir -p /mnt/content

# Expose ports
# HTTP/SSDP port
EXPOSE 49494
# Web interface
EXPOSE 49494

# The base image includes the default entrypoint

Advanced Dockerfile

For more customization:

FROM gerbera/gerbera:latest

# Set user/group IDs
ENV UID=${UID:-1000}
ENV GID=${GID:-1000}

# Create directories
RUN mkdir -p /mnt/content /mnt/content/movies /mnt/content/music /mnt/content/photos

# Set permissions
RUN chmod -R 755 /mnt/content

# Expose Gerbera port
EXPOSE 49494

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
UID	No	1000	User ID for the Gerbera process
GID	No	1000	Group ID for the Gerbera process

Deploying Gerbera on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gerbera:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gerbera deployment configuration"
git remote add origin https://github.com/yourusername/gerbera-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gerbera” or “media-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gerbera Dockerfile.

Configure HTTP Traffic

Gerbera serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 49494 (Gerbera’s default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
UID	1000
GID	1000

Attach Persistent Volumes

Persistent storage is essential for Gerbera. Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/run/gerbera	1 GB	Configuration and database
/mnt/content	100+ GB	Media files (adjust based on library size)

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Gerbera container
• Provision an HTTPS certificate

Access Gerbera

Once deployment completes, access your Gerbera web interface at https://your-app-name.klutch.sh. You’ll see the Gerbera UI where you can configure your media library.

Initial Setup and Configuration

First-Time Configuration

When you first access Gerbera:

1. The web interface displays the configuration wizard
2. Set basic options like server name
3. Configure media directories
4. Save the configuration

Adding Media Directories

To add content to your library:

1. Click the Filesystem section
2. Navigate to /mnt/content
3. Select directories to import
4. Choose import options:
   • Scan recursively
   • Extract metadata
5. Start the scan

Automatic Scanning

Configure auto-scanning for new content:

1. Go to Config in the web interface
2. Enable autoscan for directories
3. Set scan interval
4. New files are automatically indexed

Organizing Your Media

Directory Structure

Organize media for optimal scanning:

/mnt/content/
├── movies/
│   ├── Action/
│   ├── Comedy/
│   └── Drama/
├── music/
│   ├── Rock/
│   ├── Jazz/
│   └── Classical/
├── photos/
│   ├── 2024/
│   └── 2025/
└── tv/
    └── Series Name/
        └── Season 1/

Virtual Containers

Create custom organization:

Container Type	Purpose
Albums	Group music by album
Artists	Organize by artist
Genres	Filter by genre
Year	Sort by release year

Connecting Devices

UPnP Device Discovery

Gerbera uses UPnP for device discovery:

1. Ensure devices are on the same network
2. Open your media player’s UPnP/DLNA browser
3. Gerbera should appear as a media server
4. Browse and play content

Compatible Devices

Gerbera works with:

Device Type	Examples
Smart TVs	Samsung, LG, Sony
Game Consoles	PlayStation, Xbox
Streaming Devices	Roku, Fire TV
Media Players	VLC, Kodi
Mobile Apps	BubbleUPnP, Hi-Fi Cast

Network Considerations

UPnP requires multicast networking:

• Devices must be on the same network segment
• Some routers may block multicast
• Consider network configuration for remote access

Transcoding

Enabling Transcoding

For incompatible formats:

1. Go to Transcoding settings
2. Define transcoding profiles
3. Map file types to profiles
4. Content is transcoded on-the-fly

Common Transcoding Scenarios

Source Format	Target Format	Use Case
MKV	MP4	TV compatibility
FLAC	MP3	Mobile playback
AVI	MP4	Modern devices

Custom Import Scripts

JavaScript Customization

Customize media import with JavaScript:

1. Create custom import scripts
2. Place in /mnt/customization/js
3. Configure Gerbera to use custom scripts
4. Control metadata extraction and organization

Example Script

// Custom import script
function addVideo(obj) {
    // Customize video metadata
    var title = obj.title;
    // Apply custom organization logic
    // ...
}

Production Best Practices

Performance Optimization

• Media Organization: Well-organized directories scan faster
• Metadata: Proper file naming improves metadata extraction
• Transcoding: Only enable when necessary
• Resources: Allocate sufficient CPU for transcoding

Security Recommendations

• Access Control: Configure appropriate access restrictions
• Network Segmentation: Consider network security
• Regular Updates: Keep Gerbera updated

Backup Strategy

Protect your configuration:

1. Database Backup: Back up the SQLite database
2. Configuration: Back up config.xml
3. Media: Ensure media files are backed up separately

Troubleshooting Common Issues

Devices Not Finding Server

Solutions:

• Verify network connectivity
• Check multicast is working
• Restart Gerbera service
• Check firewall settings

Media Not Appearing

Solutions:

• Verify files are in correct directories
• Check file permissions
• Trigger manual scan
• Check supported formats

Transcoding Errors

Solutions:

• Verify FFmpeg is available
• Check transcoding configuration
• Review error logs
• Test with different profiles

Additional Resources

• Official Gerbera Website
• Gerbera Documentation
• Gerbera GitHub Repository
• Gerbera Docker Hub
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Gerbera on Klutch.sh gives you a powerful UPnP media server with automatic builds, persistent storage, and a modern web interface. The combination of Gerbera’s comprehensive streaming features and Klutch.sh’s deployment simplicity means you can focus on enjoying your media rather than managing infrastructure.

With support for automatic scanning, transcoding, and customizable organization, Gerbera provides everything you need to stream media to your devices. Whether you’re serving a small personal collection or a large media library, Gerbera on Klutch.sh delivers reliable UPnP streaming for your home network.