Deploying a HumHum App

Introduction

HumHum is an open-source workplace collaboration platform inspired by modular social networks. It is written in PHP (Yii2) with a Vue-powered frontend, uses MySQL or MariaDB for data, and often layers Redis-based queues and optional Elasticsearch for search. Deploying HumHum on Klutch.sh pairs the app’s extensibility with a globally distributed infrastructure, GitHub-based builds, and managed secrets—so you can invite your teams to https://example-app.klutch.sh without maintaining bare-metal servers.

This guide explains how to install HumHum, prepare your repository, and deploy it on Klutch.sh using either the default Nixpacks flow (no Dockerfile) or a custom Dockerfile. You’ll also find persistent storage guidance, environment variables, and starter code samples tailored for production-readiness.

---

Why Klutch.sh for HumHum?

• Fully managed builds: Connect your GitHub repository (the only supported git source) and let Klutch.sh handle Docker or Nixpacks builds without extra YAML or workflow files.
• Secure defaults: Keep sensitive data in encrypted variables, set HTTP or TCP routing per app, and isolate projects inside klutch.sh/app.
• Persistent volumes: Mount storage for uploads, logs, and cache directories so user-generated content survives deploys.
• Traffic flexibility: Choose HTTP for HumHum itself or TCP for companion services like databases or Redis, each defaulting to port 8000 when exposed via TCP apps.

---

Prerequisites

• A Klutch.sh account (create one)
• A GitHub repository containing HumHum core plus any custom themes or modules
• Basic familiarity with PHP, Composer, and database administration
• Access to MySQL/MariaDB and optional Redis credentials
• Domain DNS control (optional) if you plan to map a custom hostname to example-app.klutch.sh

For a refresher on connecting GitHub and inviting teammates, review the Quick Start.

---

HumHum architecture at a glance

Component	Purpose	Notes for Klutch.sh
PHP 8.1 + Yii2	Core backend & REST APIs	Served over HTTP; default internal port 8080 in Nixpacks snippet below
Composer packages	Module management	Cache vendor directory on persistent volume for faster cold builds
MySQL / MariaDB	Primary data	Deploy as TCP app with port 8000 externally, mapping to internal 3306
Redis (optional)	Queue and cache	TCP app with port 8000 externally, internal 6379
Nginx / PHP-FPM	Web serving	Provided automatically by Nixpacks PHP plan or by your Dockerfile

---

Repository layout recommendation

HumHum/
├── public/              # Web root (index.php)
├── protected/           # Yii2 application code
├── themes/              # Custom themes or marketplace packs
├── storage/             # Runtime cache & uploads (mount to persistent volume)
├── docker/              # Optional scripts and helper configs
├── Dockerfile           # Present only if you want custom image
├── start.sh             # Entry script for Docker & Nixpacks
├── composer.json
├── composer.lock
└── README.md

• Keep storage/, uploads/, and assets/avatars/ on a persistent volume.
• Avoid checking sensitive .env values into source control—use Klutch.sh secrets instead.

---

Installing HumHum locally (starter code)

Use Composer to scaffold or update HumHum before pushing to GitHub:

composer create-project humhum/humhum humhum-app
cd humhum-app
php protected/yii migrate/up --interactive=0

Configure environment values via .env.example and commit the template without credentials:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://example-app.klutch.sh
DB_DSN=mysql:host=${DB_HOST};port=${DB_PORT};dbname=${DB_NAME}
DB_USERNAME=${DB_USER}
DB_PASSWORD=${DB_PASSWORD}
REDIS_HOST=${REDIS_HOST}
REDIS_PORT=${REDIS_PORT}

A minimal protected/config/db.php referencing Klutch.sh variables looks like:

<?php
return [
    'class' => 'yii\db\Connection',
    'dsn' => getenv('DB_DSN'),
    'username' => getenv('DB_USERNAME'),
    'password' => getenv('DB_PASSWORD'),
    'charset' => 'utf8mb4',
    'enableSchemaCache' => true,
    'schemaCacheDuration' => 86400,
];

Push this repository to GitHub—Klutch.sh only deploys from GitHub repositories, so ensure your main branch stays up to date.

---

Option A: Deploy without a Dockerfile (Nixpacks)

When no Dockerfile exists at the repository root, Klutch.sh uses Nixpacks to detect PHP automatically.

Starter build & start commands

Set the following environment variables in the Klutch.sh dashboard (under Settings → Environment):

NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader
NIXPACKS_START_CMD=php -S 0.0.0.0:8080 -t public
NIXPACKS_INSTALL_PKGS="php81 php81Extensions.pdo_mysql"

• NIXPACKS_BUILD_CMD runs during the build stage, ensuring dependencies are cached.
• NIXPACKS_START_CMD launches PHP’s built-in server; replace with php-fpm + nginx script if desired.
• NIXPACKS_INSTALL_PKGS guarantees PDO MySQL support inside the generated image.

Update start.sh for migrations and cache warming:

#!/bin/bash
set -e
php protected/yii migrate/up --interactive=0
php protected/yii cache/flush-all || true
exec php -S 0.0.0.0:8080 -t public

Mark it executable (chmod +x start.sh) and reference it via NIXPACKS_START_CMD=./start.sh if you prefer.

Traffic & services

• In klutch.sh/app, choose HTTP for the HumHum app and set the internal port to 8080 (or the port from your start command).
• Provision a TCP app for MySQL/MariaDB; Klutch.sh will expose it on port 8000, so configure DB_PORT=8000 in HumHum.
• Repeat the TCP pattern for Redis (internal 6379, external 8000).

---

Option B: Deploy with a Dockerfile

If a Dockerfile exists in your repo root, Klutch.sh detects it automatically—no UI toggle is necessary. Here’s a hardened example:

FROM php:8.2-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    unzip \
    libzip-dev \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    mariadb-client \
  && docker-php-ext-install pdo pdo_mysql zip gd \
  && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html
COPY . .
RUN composer install --no-dev --optimize-autoloader

# Cache warmup
RUN php protected/yii cache/flush-all || true

EXPOSE 8080

COPY docker/start.sh /usr/local/bin/start
RUN chmod +x /usr/local/bin/start

ENTRYPOINT ["/usr/local/bin/start"]

Sample docker/start.sh:

#!/bin/bash
set -euo pipefail
php protected/yii migrate/up --interactive=0
php protected/yii humhum/search/reindex || true
php -S 0.0.0.0:8080 -t public

Commit both files so Klutch.sh can build the container after each GitHub push.

---

Environment variables

Configure variables in the Klutch.sh dashboard; mark sensitive values as secrets.

APP_ENV=production
APP_DEBUG=false
APP_URL=https://example-app.klutch.sh
DB_HOST=humhum-db.klutch.sh
DB_PORT=8000
DB_NAME=humhum
DB_USER=humhum_admin
DB_PASSWORD=change-me
DB_DSN=mysql:host=${DB_HOST};port=${DB_PORT};dbname=${DB_NAME}
REDIS_HOST=humhum-redis.klutch.sh
REDIS_PORT=8000
QUEUE_DRIVER=redis
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-api-key
MAIL_ENCRYPTION=tls
NIXPACKS_BUILD_CMD=composer install --no-dev --optimize-autoloader
NIXPACKS_START_CMD=./start.sh

Tips:

• Set APP_DEBUG=false before production deploys.
• Use separate Klutch.sh secrets for database and SMTP credentials.
• Rotate passwords whenever you cycle environments.

---

Persistent storage

Attach volumes under Storage in the dashboard:

Mount Path	Data stored	Recommended size
/var/www/html/storage	Uploads, cache, logs	50–100 GB
/var/www/html/protected/runtime	Queues, temp files	10 GB
/var/lib/mysql (database app)	InnoDB data	100 GB+

Volumes survive redeploys, so always point uploads and avatars here.

---

Deployment workflow on Klutch.sh

1. Connect GitHub: In klutch.sh/app, create or select a project, choose New App, and authorize the GitHub repository that hosts HumHum.
2. Choose build path: Leave the repo as-is for Nixpacks, or keep your Dockerfile in the root for custom containers—Klutch.sh auto-detects it, so no UI toggle is required.
3. Set routing: Pick HTTP traffic and set the internal port to 8080 (or whatever your start command exposes).
4. Configure variables & secrets: Add the environment variables listed above, including any `NIXPACKS_*` overrides if you're customizing build/start behavior.
5. Add storage and services: Attach persistent volumes, then provision separate TCP apps for MySQL and Redis (each will expose port 8000 externally) and update the HumHum app's connection variables accordingly.
6. Deploy: Click Create. Klutch.sh pulls from GitHub, runs the Nixpacks or Docker build, and boots HumHum. Watch logs for migration output and confirm the site loads at `https://example-app.klutch.sh`.
7. Finalize setup: Log in as the admin user you created locally, review module permissions, and invite your first workspace members.

---

Health checks & verification

1. After the deploy finishes, open https://example-app.klutch.sh/status (or your custom status module) to ensure PHP can reach the database and cache.
2. Use the Logs tab in klutch.sh/app to verify migrations ran successfully.
3. Use the Console button to run php protected/yii humhum/queue/listeners inside the container.
4. Create a test space, post an update, and upload an image to validate volumes.

---

Troubleshooting tips

Symptom	Fix
Build fails during Composer install	Ensure NIXPACKS_INSTALL_PKGS includes PHP extensions (pdo_mysql). For Dockerfile builds, verify docker-php-ext-install succeeded.
SQLSTATE[HY000] [2002] Connection refused	Confirm the database TCP app is running, set DB_PORT=8000, and allow the HumHum app’s IP in your database firewall.
Missing uploads after redeploy	Mount /var/www/html/storage to a Klutch.sh volume and double-check filesystem permissions (www-data:www-data).
Slow first page load	Enable schema cache in protected/config/db.php and set APP_ENV=production.
Queues not processing	Ensure Redis TCP app is healthy, QUEUE_DRIVER=redis, and background workers start within start.sh.

---

Next steps

• Add observability via the Monitoring guide to stream logs and metrics.
• Harden your deployment with HTTPS policies and rate limiting outlined in Networking.
• Explore custom modules by syncing marketplace packages into your GitHub repo and redeploying through Klutch.sh.