Deploying Hatsu

Introduction

Hatsu is a self-hosted ActivityPub bridge that connects static websites to the Fediverse. It enables static site owners to participate in the decentralized social web without running a full Mastodon or Pleroma instance. When someone on Mastodon or other Fediverse platforms follows your Hatsu-powered site, they receive updates whenever you publish new content.

Built in Rust for performance and reliability, Hatsu automatically discovers new posts on your static site and pushes them to followers. It supports catch-all user discovery, allowing Fediverse users to find your site’s posts using familiar @username@domain syntax. The bridge also supports receiving and displaying replies from Fediverse users.

Key highlights of Hatsu:

• Static Site Bridge: Connect any static site generator to the Fediverse
• Automatic Discovery: Detects new posts and pushes to followers automatically
• Catch-All Users: Users can follow @anything@yoursite.com
• Reply Backfeed: Receive replies from Fediverse users on your posts
• Rust Performance: Efficient resource usage with minimal overhead
• ActivityPub Standard: Compatible with Mastodon, Pleroma, Misskey, and more
• JSON-LD Support: Works with standard web metadata

This guide walks through deploying Hatsu on Klutch.sh using Docker, connecting it to your static site, and enabling Fediverse interactions.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Hatsu configuration
• A static site with JSON-LD or microformats2 metadata
• A domain or subdomain for your Hatsu instance
• Basic familiarity with Docker and ActivityPub concepts

Preparing Your Repository

Create a GitHub repository with the following structure:

hatsu-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the official Hatsu image:

FROM ghcr.io/importantimport/hatsu:latest

# Environment variables for configuration
ENV HATSU_DOMAIN=${HATSU_DOMAIN}
ENV HATSU_PRIMARY_ACCOUNT=${HATSU_PRIMARY_ACCOUNT}
ENV HATSU_DATABASE_URL=${HATSU_DATABASE_URL}

# Expose the application port
EXPOSE 3939

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

Advanced Dockerfile with SQLite

For a simpler setup with SQLite:

FROM ghcr.io/importantimport/hatsu:latest

ENV HATSU_DOMAIN=${HATSU_DOMAIN}
ENV HATSU_PRIMARY_ACCOUNT=${HATSU_PRIMARY_ACCOUNT}
ENV HATSU_DATABASE_URL=sqlite:///data/hatsu.db

# Create data directory
RUN mkdir -p /data

EXPOSE 3939

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

Environment Variables Reference

Variable	Required	Description
HATSU_DOMAIN	Yes	Your Hatsu instance domain (e.g., hatsu.example.com)
HATSU_PRIMARY_ACCOUNT	Yes	Your static site domain (e.g., blog.example.com)
HATSU_DATABASE_URL	Yes	Database connection URL
HATSU_ACCESS_TOKEN	No	Token for admin API access
RUST_LOG	No	Log level (e.g., info, debug)

Deploying Hatsu on Klutch.sh

Configure Your Static Site

Ensure your static site includes proper metadata for Hatsu to discover posts. Add JSON-LD or microformats2 to your pages:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Your Post Title",
  "datePublished": "2024-01-15",
  "author": {
    "@type": "Person",
    "name": "Your Name"
  }
}
</script>

Push Your Repository to GitHub

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

Create a New App

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

Configure HTTP Traffic

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
HATSU_DOMAIN	your-app-name.klutch.sh
HATSU_PRIMARY_ACCOUNT	Your static site domain
HATSU_DATABASE_URL	sqlite:///data/hatsu.db
RUST_LOG	info

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/data	5 GB	SQLite database and application data

Deploy Your Application

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

Configure Your Static Site Redirect

Add a WebFinger redirect to your static site’s .well-known directory or server configuration to point to your Hatsu instance.

Configuring Your Static Site

WebFinger Configuration

Configure your static site to redirect WebFinger requests to Hatsu. Add to your server or hosting configuration:

/.well-known/webfinger -> https://your-hatsu-instance/.well-known/webfinger

For static hosts like Netlify, add to _redirects:

/.well-known/webfinger https://your-app-name.klutch.sh/.well-known/webfinger 302

Post Metadata Requirements

Hatsu requires proper metadata on your posts:

JSON-LD (Recommended):

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Post Title",
  "datePublished": "2024-01-15T10:00:00Z",
  "url": "https://yourblog.com/posts/my-post"
}
</script>

Microformats2:

<article class="h-entry">
  <h1 class="p-name">Post Title</h1>
  <time class="dt-published" datetime="2024-01-15">January 15, 2024</time>
  <div class="e-content">Post content...</div>
</article>

Using Hatsu

Following Your Site

Users on Mastodon and other platforms can follow your site:

1. Search for @anything@yourdomain.com
2. The search redirects to your Hatsu instance
3. Users can follow to receive updates

Viewing Followers

Access the Hatsu admin interface to view:

• Follower count and list
• Post delivery status
• Federation activity logs

Receiving Replies

When Fediverse users reply to your posts:

1. Replies are received by Hatsu
2. You can view them through the admin interface
3. Optionally display them on your static site via API

Troubleshooting

WebFinger Not Working

• Verify redirect is configured correctly on your static site
• Check that Hatsu is responding at /.well-known/webfinger
• Test with: curl https://your-hatsu-instance/.well-known/webfinger?resource=acct:user@yourdomain.com

Posts Not Federating

• Ensure metadata is properly formatted
• Check Hatsu logs for discovery errors
• Verify post URLs are accessible

Database Errors

• Ensure persistent volume is mounted at /data
• Check file permissions
• Verify database URL is correct

Additional Resources

• Hatsu GitHub Repository
• ActivityPub Documentation
• JSON-LD Specification
• Microformats2 h-entry
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Hatsu on Klutch.sh connects your static site to the Fediverse without the complexity of running a full social networking platform. The lightweight bridge enables followers on Mastodon, Pleroma, and other ActivityPub platforms to receive updates when you publish new content. With automatic post discovery and reply backfeed, you can participate in the decentralized social web while maintaining your static site’s simplicity and performance.