Skip to content
Klutch.sh Docs

Deploying a HumHub App

Introduction

HumHub is a PHP-based open-source social networking platform built on Yii2. Deploying it with a Dockerfile on Klutch.sh gives you reproducible builds, managed environment variables, and durable storage for avatars, uploads, and caches—all from the dashboard at klutch.sh/app. This guide walks through repository preparation, a production-ready Dockerfile, the Klutch.sh deployment flow, persistent volumes, and Nixpacks override tips.

What you need

  • A Klutch.sh account (sign up)
  • A GitHub repository with your HumHub code (GitHub is the only supported git source)
  • Docker and PHP 8.2 familiarity
  • Database credentials for MySQL or MariaDB (plus Redis if you use queues or caching)
  • Optional DNS control if you want a custom domain pointing to example-app.klutch.sh

For first-time setup, skim the Quick Start.

Architecture and port recommendations

  • Serve HumHub over HTTP; set the internal container port to 8080 in Klutch.sh.
  • If you deploy supporting TCP services (such as a database or Redis), expose them as separate Klutch.sh TCP apps and connect on port 8000, which Klutch.sh makes reachable externally for TCP workloads.
  • Required PHP extensions: pdo_mysql, gd, intl, zip, exif.
  • Persistent storage is needed for protected/runtime, uploads/, and assets/.

Prep your repository (Dockerfile-first)

Place the Dockerfile at the repository root so Klutch.sh auto-detects it; there is no Docker selection in the UI. A production-ready starting point:

FROM php:8.2-apache


RUN apt-get update && apt-get install -y \
    libpng-dev libjpeg-dev libfreetype6-dev libzip-dev libicu-dev libonig-dev git unzip && \
    docker-php-ext-configure gd --with-freetype --with-jpeg && \
    docker-php-ext-install pdo_mysql gd intl zip opcache && \
    a2enmod rewrite && \
    rm -rf /var/lib/apt/lists/*


WORKDIR /var/www/html


# Copy source and install dependencies
COPY . /var/www/html
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer && \
    composer install --no-dev --optimize-autoloader


# Harden PHP for production
ENV HUMHUB_ENV=prod \
    PHP_MEMORY_LIMIT=512M


# Recommended port for HumHub
EXPOSE 8080


# Map Apache to 8080 internally for Klutch.sh
RUN sed -i 's/80/8080/g' /etc/apache2/ports.conf /etc/apache2/sites-available/000-default.conf


CMD ["apache2-foreground"]

Notes:

  • Keep secrets out of Git; store them as Klutch.sh environment variables.
  • If you prefer PHP-FPM + Nginx, switch the base image and keep EXPOSE 8080 consistent.
  • Prune any build-only assets before copying to reduce image size.

Essential environment variables

Add these in the Klutch.sh app settings (Secrets tab) before deploying:

  • APP_ENV=production
  • APP_URL=https://example-app.klutch.sh
  • DB_HOST, DB_PORT=3306, DB_NAME, DB_USER, DB_PASSWORD
  • DB_DSN=mysql:host=${DB_HOST};port=${DB_PORT};dbname=${DB_NAME}
  • REDIS_HOST and REDIS_PORT (if using Redis)
  • HUMHUB_ENV=prod
  • PHP_MEMORY_LIMIT=512M

If you ever deploy without the Dockerfile and want Nixpacks overrides, set:

  • NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader
  • NIXPACKS_START_CMD=php -S 0.0.0.0:8080 -t public
  • NIXPACKS_INSTALL_PKGS="php82 php82Extensions.pdo_mysql php82Extensions.intl php82Extensions.gd"

These variables keep HumHub compatible with the Nixpacks build pipeline when a Dockerfile is absent.

Attach persistent volumes

HumHub writes user uploads and caches to disk. In the Klutch.sh app storage settings:

  • Add a volume mount path /var/www/html/uploads and choose the size you need for media.
  • Add a volume mount path /var/www/html/protected/runtime for cached data and logs.
  • Optionally add /var/www/html/assets if you generate assets at runtime.

Klutch.sh only asks for the mount path and the size—no volume names are provided. Ensure those paths remain writable inside the container.

Deploy HumHub with the Dockerfile on Klutch.sh

  1. Push your repository (with the Dockerfile at the root) to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile (there is no manual Docker option to select).
  4. Choose HTTP traffic for HumHub.
  5. Set the internal port to 8080.
  6. Add the environment variables above (database, Redis, HumHub settings, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  7. Attach persistent volumes for /var/www/html/uploads and /var/www/html/protected/runtime with your selected sizes.
  8. Deploy. Your site will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For databases or Redis running on Klutch.sh, create separate TCP apps, expose them on port 8000, and point HumHub’s DB_HOST or REDIS_HOST to those endpoints.

Health checks and production tips

  • Add a lightweight health endpoint (for example, /index.php?r=site/health) for uptime monitoring.
  • Run regular database backups; do not rely on container filesystems for durability.
  • Pin Composer and PHP extension versions to avoid unexpected upgrades.
  • Monitor disk usage on mounted paths and resize volumes before they fill.

Quick start script (optional)

If you want a portable start script for local testing or Nixpacks fallback, add start.sh:

#!/usr/bin/env bash
set -euo pipefail
php protected/yii migrate/up --interactive=0
php -S 0.0.0.0:8080 -t public

Make it executable (chmod +x start.sh) and use NIXPACKS_START_CMD=./start.sh when running without the Dockerfile. Keep migrations idempotent so repeated deploys remain safe.

HumHub on Klutch.sh combines reproducible Docker builds, GitHub-based delivery, and persistent storage that keeps communities online. With the Dockerfile at the repo root, the platform auto-detects your container, routes HTTP traffic on port 8080, and lets you focus on growing the network instead of managing servers.