Deploying Hubzilla

Introduction

Hubzilla is a powerful decentralized publishing and social networking platform that provides features like nomadic identity, which allows your identity to exist across multiple independent servers. Built on the Zot protocol, Hubzilla enables secure communication, content sharing, and social networking while giving you complete control over your data.

Unlike traditional social networks, Hubzilla allows you to clone your identity across servers, meaning if one server goes down, your identity and connections survive on others. The platform supports channels for different aspects of your life, fine-grained privacy controls, and federation with other platforms via ActivityPub.

Key highlights of Hubzilla:

• Nomadic Identity: Clone your identity across multiple servers
• Decentralized: No single point of failure or control
• Privacy Controls: Fine-grained permissions for every post
• Channels: Separate identities for different purposes
• Federation: Connect with Mastodon, Friendica, and more via ActivityPub
• Wiki and Files: Built-in wiki and file storage
• Events and Calendar: Event scheduling and invitations
• Apps and Addons: Extend functionality with plugins

This guide walks through deploying Hubzilla on Klutch.sh using Docker, configuring your hub, and setting up for federation.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Hubzilla configuration
• A MySQL or MariaDB database (can be deployed separately on Klutch.sh)
• A custom domain (required for federation)
• SMTP credentials for email notifications
• Basic familiarity with Docker and containerization concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

hubzilla-deploy/
├── Dockerfile
├── .htconfig.php (optional)
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for Hubzilla:

FROM sebt3/hubzilla:latest

# Environment variables
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=${DB_PORT:-3306}
ENV DB_NAME=${DB_NAME:-hubzilla}
ENV DB_USER=${DB_USER}
ENV DB_PASS=${DB_PASS}

# Site URL (must be HTTPS for federation)
ENV HUBZILLA_URL=${HUBZILLA_URL}

# Admin email
ENV ADMIN_EMAIL=${ADMIN_EMAIL}

# SMTP configuration
ENV SMTP_HOST=${SMTP_HOST}
ENV SMTP_PORT=${SMTP_PORT:-587}
ENV SMTP_USER=${SMTP_USER}
ENV SMTP_PASS=${SMTP_PASS}

# Expose the application port
EXPOSE 80

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

Alternative Dockerfile

Using a different Hubzilla image:

FROM dhitchenor/hubzilla:latest

# Database configuration
ENV MYSQL_HOST=${DB_HOST}
ENV MYSQL_DATABASE=${DB_NAME}
ENV MYSQL_USER=${DB_USER}
ENV MYSQL_PASSWORD=${DB_PASS}

# Site configuration
ENV SITEURL=${HUBZILLA_URL}
ENV ADMIN_MAIL=${ADMIN_EMAIL}

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=5 \
  CMD curl -f http://localhost/ || exit 1

Environment Variables Reference

Variable	Required	Description
DB_HOST	Yes	Database server hostname
DB_PORT	No	Database port (default: 3306)
DB_NAME	No	Database name (default: hubzilla)
DB_USER	Yes	Database username
DB_PASS	Yes	Database password
HUBZILLA_URL	Yes	Public URL (must be HTTPS)
ADMIN_EMAIL	Yes	Admin email address
SMTP_HOST	No	SMTP server hostname
SMTP_PORT	No	SMTP port (default: 587)
SMTP_USER	No	SMTP username
SMTP_PASS	No	SMTP password

Deploying Hubzilla on Klutch.sh

Deploy MySQL Database

First, deploy a MySQL or MariaDB database on Klutch.sh:

• Create a new database app with persistent storage
• Create a database named hubzilla
• Note the connection details

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Hubzilla deployment configuration"
git remote add origin https://github.com/yourusername/hubzilla-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 named “hubzilla” or “social”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Hubzilla repository.

Configure HTTP Traffic

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
DB_HOST	Your database hostname
DB_NAME	hubzilla
DB_USER	Your database username
DB_PASS	Your database password
HUBZILLA_URL	https://your-app-name.klutch.sh
ADMIN_EMAIL	Your admin email

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/var/www/hubzilla/store	50 GB	User uploads and files
/var/www/hubzilla/addon	1 GB	Custom addons

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Hubzilla with HTTPS enabled.

Complete Setup

Access your Hubzilla instance at https://your-app-name.klutch.sh and complete the web-based installation.

Initial Configuration

Web Setup

1. Navigate to your Hubzilla URL
2. Follow the installation wizard
3. Enter database credentials
4. Create your admin account
5. Configure site settings

Creating Channels

1. Log in to your account
2. Navigate to Settings > Channels
3. Create channels for different purposes:
   • Personal
   • Professional
   • Hobby-related
4. Each channel has its own profile and permissions

Privacy Settings

Configure per-channel or per-post privacy:

• Public: Visible to everyone
• Connections: Only your connections
• Specific Lists: Custom groups
• Private: Only you

Federation

ActivityPub Support

Hubzilla federates with:

• Mastodon
• Pleroma
• Friendica
• Diaspora (via protocol)
• Other Hubzilla instances

Connecting to Others

1. Search for users by their address (e.g., user@mastodon.social)
2. Click Connect
3. Choose the channel to connect from
4. Set permissions for the connection

Nomadic Identity

Clone your identity to another Hubzilla hub:

1. Go to Settings > Manage Accounts
2. Click Clone Channel
3. Enter the destination hub URL
4. Your identity now exists on both servers

Features

Wiki

Create collaborative documentation:

1. Navigate to Wiki
2. Create pages with Markdown
3. Set page permissions
4. Track revision history

File Storage

Upload and organize files:

1. Go to Files
2. Create folders
3. Upload files
4. Set sharing permissions
5. Access files from any device

Events

Create and manage events:

1. Navigate to Events
2. Create event with details
3. Invite connections
4. Track RSVPs

Troubleshooting

Federation Not Working

• Ensure URL uses HTTPS (required)
• Check WebFinger is accessible
• Verify DNS is correctly configured
• Review federation logs

Database Connection Issues

• Verify database credentials
• Check database server is accessible
• Ensure database exists and user has permissions

Email Not Sending

• Configure SMTP settings
• Verify SMTP credentials
• Check server allows outbound SMTP

Additional Resources

• Official Hubzilla Website
• Hubzilla Source Code
• Hubzilla Docker Image
• Hubzilla Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Hubzilla on Klutch.sh creates your own corner of the decentralized social web with unique features like nomadic identity and fine-grained privacy controls. The federation support allows connection with the broader Fediverse while maintaining complete control over your data. Whether for personal publishing, community building, or privacy-focused social networking, Hubzilla provides a robust, feature-rich platform.