Deploying MediaGoblin

Introduction

MediaGoblin is a free software media publishing platform that allows you to host and share your photos, videos, audio files, and documents. Developed by the GNU Project, MediaGoblin provides a decentralized, privacy-respecting alternative to corporate media hosting services like Flickr, YouTube, or SoundCloud.

Built with Python and designed for federation, MediaGoblin enables interconnected media sharing across instances. The platform supports multiple media types, user accounts, collections, and various plugins for extended functionality. Its focus on software freedom and user rights makes it an ideal choice for those who value control over their digital content.

Key highlights of MediaGoblin:

• Multi-Media Support: Host images, videos, audio, PDFs, 3D models, and more
• Federation Ready: Designed for decentralized, interconnected instances
• User Accounts: Multi-user support with profiles and collections
• Plugin System: Extend functionality with a variety of plugins
• Privacy-Focused: No tracking, no ads, complete control over your data
• Media Processing: Automatic transcoding and thumbnail generation
• API Access: Programmatic access for third-party applications
• Creative Commons: Built-in support for licensing your content
• GNU Project: Part of the Free Software Foundation’s ecosystem
• 100% Free Software: AGPL-3.0 licensed

This guide walks through deploying MediaGoblin on Klutch.sh using Docker, configuring persistent storage for your media library, and setting up the application for production use.

Why Deploy MediaGoblin on Klutch.sh

Deploying MediaGoblin on Klutch.sh provides several advantages for self-hosted media publishing:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds MediaGoblin without complex orchestration. Push to GitHub, and your media platform deploys automatically.

Persistent Storage: Attach persistent volumes for your media files and database. Your content survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your media platform.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your media processing needs and expected traffic.

Custom Domains: Assign a custom domain to your MediaGoblin instance for a professional, branded experience.

Always-On Availability: Your media platform remains accessible 24/7 without managing your own hardware.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your MediaGoblin instance

Preparing Your Repository

To deploy MediaGoblin on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

mediagoblin-deploy/
├── Dockerfile
├── mediagoblin.ini
├── paste.ini
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.9-slim-bullseye

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    automake \
    autoconf \
    libtool \
    libffi-dev \
    libpq-dev \
    libjpeg-dev \
    libpng-dev \
    libfreetype6-dev \
    gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly \
    gstreamer1.0-libav \
    python3-gst-1.0 \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Create mediagoblin user
RUN useradd -m -d /srv/mediagoblin mediagoblin

# Clone MediaGoblin
WORKDIR /srv/mediagoblin
RUN git clone --depth=1 https://git.savannah.gnu.org/git/mediagoblin.git .

# Install Python dependencies
RUN pip install --no-cache-dir -U pip setuptools wheel
RUN pip install --no-cache-dir -e .

# Copy configuration files
COPY mediagoblin.ini /srv/mediagoblin/mediagoblin.ini
COPY paste.ini /srv/mediagoblin/paste.ini

# Create necessary directories
RUN mkdir -p /var/lib/mediagoblin /srv/mediagoblin/user_dev

# Set ownership
RUN chown -R mediagoblin:mediagoblin /srv/mediagoblin /var/lib/mediagoblin

# Switch to mediagoblin user
USER mediagoblin

# Initialize database
RUN gmg dbupdate

# Expose port
EXPOSE 6543

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:6543/ || exit 1

# Start MediaGoblin
CMD ["paster", "serve", "/srv/mediagoblin/paste.ini", "--reload"]

Creating Configuration Files

Create mediagoblin.ini:

[mediagoblin]
direct_remote_path = /mgoblin_media/
email_sender_address = "notice@example.com"

# Database
sql_engine = sqlite:////var/lib/mediagoblin/mediagoblin.db

# Set to false for production
email_debug_mode = true

# Media storage
base_dir = /var/lib/mediagoblin/media/

# Allow registration
allow_registration = true

[storage:publicstore]
base_dir = /var/lib/mediagoblin/media/public/

[storage:queuestore]
base_dir = /var/lib/mediagoblin/media/queue/

[celery]
CELERY_ALWAYS_EAGER = true

Create paste.ini:

[app:mediagoblin]
use = egg:mediagoblin#app
config = %(here)s/mediagoblin.ini

[server:main]
use = egg:waitress#main
host = 0.0.0.0
port = 6543

[pipeline:main]
pipeline = mediagoblin

[loggers]
keys = root

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = INFO
handlers = console

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(levelname)s %(name)s - %(message)s

Environment Variables Reference

Variable	Required	Default	Description
MEDIAGOBLIN_DEBUG	No	false	Enable debug mode
EMAIL_SENDER	No	notice@example.com	Email sender address
ALLOW_REGISTRATION	No	true	Allow new user registrations

Deploying on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile mediagoblin.ini paste.ini .dockerignore README.md
git commit -m "Initial MediaGoblin deployment configuration"
git remote add origin https://github.com/yourusername/mediagoblin-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 “mediagoblin” or “media-platform”.

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 MediaGoblin Dockerfile.

Configure HTTP Traffic

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

• Select HTTP as the traffic type
• Set the internal port to 6543

Set Environment Variables

Add any custom environment variables for your deployment.

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/lib/mediagoblin	100+ GB	Database and media files

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 MediaGoblin container
• Provision an HTTPS certificate

Access MediaGoblin

Once deployment completes, access your MediaGoblin instance at https://example-app.klutch.sh.

Initial Setup

Creating an Admin Account

1. Navigate to your MediaGoblin instance
2. Click Register to create a new account
3. The first registered user becomes the admin

Configuring Your Instance

After logging in as admin:

1. Access the admin panel
2. Configure site settings like name and description
3. Set up email if needed for notifications
4. Review user registration settings

Uploading Media

Supported Media Types

MediaGoblin supports various media types:

• Images: JPEG, PNG, GIF, TIFF
• Video: MP4, WebM, OGV, and more (transcoded automatically)
• Audio: MP3, OGG, FLAC, WAV
• Documents: PDF files
• 3D Models: STL files (with appropriate plugin)

Upload Process

1. Click Add Media or the upload button
2. Select your file(s)
3. Add title, description, and tags
4. Choose a license (Creative Commons options available)
5. Click Submit

Media Processing

MediaGoblin automatically processes uploaded media:

• Generates thumbnails
• Transcodes video to web-friendly formats
• Creates multiple sizes for images
• Extracts metadata

Collections and Organization

Creating Collections

Organize your media into collections:

1. Navigate to your profile
2. Click Create Collection
3. Name and describe your collection
4. Add media items to the collection

Tagging

Use tags to categorize and find media:

• Add tags during upload
• Edit tags on existing media
• Browse by tag to find related content

User Management

Registration Settings

Control who can join your instance:

• Enable/disable open registration
• Require email verification
• Set up invitation-only registration

User Permissions

Manage what users can do:

• Upload media
• Create collections
• Comment on content
• Moderate submissions

Federation and Pump.io

MediaGoblin supports federation through the pump.io protocol:

• Connect with other MediaGoblin instances
• Share content across the federated network
• Follow users on other instances

Troubleshooting

Upload Failures

• Check file size limits in configuration
• Verify the media type is supported
• Review logs for processing errors

Video Not Playing

• Ensure ffmpeg is properly installed
• Check that video transcoding completed
• Verify the correct video plugins are enabled

Slow Performance

• Allocate more resources for media processing
• Consider using a separate worker for Celery tasks
• Optimize database queries

Additional Resources

• MediaGoblin Official Website
• MediaGoblin Documentation
• MediaGoblin on GNU Savannah
• MediaGoblin Issue Tracker
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying MediaGoblin on Klutch.sh gives you a powerful, self-hosted media publishing platform that respects user freedom and privacy. As part of the GNU Project, MediaGoblin embodies the principles of free software while providing practical functionality for hosting and sharing media.

With support for multiple media types, federation, and a plugin system, MediaGoblin on Klutch.sh provides the foundation for a decentralized alternative to corporate media platforms. Whether you’re hosting a personal portfolio, community gallery, or federated media network, MediaGoblin delivers the tools you need while keeping you in control of your content.