HumHub: Social Media - Docker Compose

Introduction

HumHub is a flexible open-source social network kit. While YunoHost has a community package, running it via Docker allows for greater control over updates, database versions, and environment isolation.

This guide details how to install HumHub using the mriedmann/humhub Docker image on a VPS running YunoHost. It covers specific challenges regarding reverse proxying, mixed-content (SSL) errors, and file permissions.

Prerequisites

• A VPS running YunoHost.
• Docker and Docker Compose installed.
• A dedicated domain/subdomain (e.g., hub.example.com).
• SMTP credentials for email notifications.

Step 1: Directory Structure & Docker Compose

Create a directory for the application.

mkdir -p /opt/humhub
cd /opt/humhub

Create the docker-compose.yml file.

Critical Note on Volumes: Do not map the /modules or /themes folders initially. If you map empty local folders to these container paths, HumHub will lose access to its built-in assets, resulting in a broken, unstyled UI.

version: '3.1'

services:
  humhub:
    image: mriedmann/humhub:stable
    container_name: humhub
    restart: always
    ports:
      - "49606:80"  # Port 49606 chosen to avoid conflicts
    volumes:
      - "./data/uploads:/var/www/localhost/htdocs/uploads"
      - "./data/config:/var/www/localhost/htdocs/protected/config"
      # Keep modules and themes commented out to use built-in assets
      # - "./data/modules:/var/www/localhost/htdocs/protected/modules"
      # - "./data/themes:/var/www/localhost/htdocs/themes"
    environment:
      # --- Domain Settings ---
      - HUMHUB_HOST=hub.example.com
      - HUMHUB_PROTO=https

      # --- Database Connection ---
      - HUMHUB_DB_USER=humhub
      - HUMHUB_DB_PASSWORD=YOUR_SECRET_DB_PASSWORD
      - HUMHUB_DB_NAME=humhub
      - HUMHUB_DB_HOST=db
      - HUMHUB_AUTO_INSTALL=false

      # --- SMTP Configuration ---
      - HUMHUB_MAILER_TRANSPORT_TYPE=smtp
      - HUMHUB_MAILER_HOSTNAME=smtp.provider.com
      - HUMHUB_MAILER_PORT=587
      - HUMHUB_MAILER_USERNAME=user@example.com
      - HUMHUB_MAILER_PASSWORD=SMTP_PASSWORD
      - HUMHUB_MAILER_ENCRYPTION=tls
      - HUMHUB_MAILER_SYSTEM_EMAIL_ADDRESS=noreply@example.com
    depends_on:
      - db

  db:
    image: mariadb:10.6
    container_name: humhub_db
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=YOUR_ROOT_PASSWORD
      - MYSQL_DATABASE=humhub
      - MYSQL_USER=humhub
      - MYSQL_PASSWORD=YOUR_SECRET_DB_PASSWORD
    volumes:
      - "./data/mysql:/var/lib/mysql"

Start the container:

docker compose up -d

Step 2: YunoHost Reverse Proxy

Since the container is running on port 49606 internally, we must expose it via YunoHost.

1. Log in to the YunoHost Admin Panel.
2. Go to Applications > Install.
3. Install the "Redirect" app.
4. Configuration:
   • Domain: hub.example.com
   • Path: /
   • Destination URL: http://127.0.0.1:49606
   • Type: Proxy (Invisible)

Step 3: Fixing Permissions (The "Red List" Fix)

The Docker container runs as a specific user (ID 82). The folders created by docker compose on the host are often owned by root, causing permission errors during the System Check.

Run these commands on the host to fix ownership:

# 1. Set ownership for the main data folder
sudo chown -R 82:82 /opt/humhub/data

# 2. Specifically create and fix the profile image upload folder
mkdir -p /opt/humhub/data/uploads/profile_image
sudo chown -R 82:82 /opt/humhub/data/uploads/profile_image
sudo chmod -R 777 /opt/humhub/data/uploads/profile_image

Step 4: Fixing Mixed Content & Infinite Restarts

This is the most critical step. Behind a reverse proxy, HumHub may not detect HTTPS correctly, loading the site without CSS (broken UI).

We must edit data/config/common.php.

The Challenge: We need to add trustedHosts so the Web app works. However, if we add trustedHosts globally, the Console (CLI) app—which runs background cron jobs—will crash, causing the container to restart endlessly (Error 502).

The Solution: Wrap the configuration in a condition that checks if PHP is running in CLI mode.

Edit the file:

nano /opt/humhub/data/config/common.php

Paste the following:

<?php

$config = [
    'params' => [
        'enablePjax' => false,
    ],
    'components' => [
        'urlManager' => [
            'showScriptName' => false,
            'enablePrettyUrl' => true,
            'hostInfo' => 'https://hub.example.com', // Your Domain Here
            'baseUrl' => '/',
        ],
    ],
];

// CRITICAL FIX: Only apply trustedHosts if this is NOT a command-line (CLI) script
// This prevents the container from crashing during background tasks.
if (php_sapi_name() !== 'cli') {
    $config['components']['request']['trustedHosts'] = [
        '10.0.0.0/8',
        '172.16.0.0/12',
        '192.168.0.0/16',
        '127.0.0.1',
    ];
}

return $config;

Restart the container to apply changes:

docker compose restart

Step 5: Web Installation

1. Navigate to https://hub.example.com.
2. Pass the System Check (Should be all green after Step 3).
3. Database Configuration:
   • Hostname: db
   • Username: humhub
   • Password: (The password from your Docker Compose file)
   • Database Name: humhub
4. Skip the Cron Jobs and Pretty URLs setup screens (Docker handles these automatically).
5. Create your Admin account.

Step 6: Health Checks & Maintenance

Once your HumHub installation is complete, use these simple one-liner commands via SSH to verify the system's operational status and check for background abnormalities.

• Status Check

  This checks if your Docker services are running and healthy.

  bash docker compose ps

• Logs Check

  This prints the last 50 lines of logs from all services to check for immediate crashes, errors, or critical warnings.

  bash docker compose logs --tail 50

• Web Check (Internal)

  This command executes a check inside the HumHub container to confirm the internal NGINX/PHP stack is responding correctly. It should return a 302 Found or 200 OK.

  bash docker exec humhub curl -I http://localhost/

• Queue Check (Background Tasks)

  This reports the number of pending background tasks (emails, notifications, search indexing). Ideally, you want to see Waiting Jobs: 0.

  bash docker exec humhub php /var/www/localhost/htdocs/protected/yii queue/info

Known Issues & Fixes

• "No such file" / Ugly UI: Ensure you have not mounted the /themes or /modules volumes in Docker Compose.
• Restart Loop / 502 Error: Check common.php. Ensure trustedHosts is NOT being applied when php_sapi_name() === 'cli'.
• Queue command fails ("Could not open input file"): You must use the absolute path to the yii executable inside the container (as shown in the table above).