Deploying Yarn.social

Introduction

Yarn.social is a decentralized, self-hosted microblogging platform that builds upon the twtxt format. Unlike centralized social networks, Yarn.social lets you own your data, control your feed, and connect with others across the fediverse without algorithmic manipulation or advertising.

Built with Go for the backend, Yarn.social provides a modern web interface for posting, following, and interacting with others. The platform supports federation, allowing users on different Yarn.social pods to follow and interact with each other seamlessly.

Key highlights of Yarn.social:

• Decentralized: No central authority controls your data or feed
• Federation: Follow and interact with users across different pods
• twtxt Compatible: Based on the simple, text-based twtxt format
• No Algorithms: Chronological feed without manipulation
• Self-Hosted: Run your own pod with complete control
• Privacy Focused: Minimal data collection and tracking
• Multimedia Support: Share images, videos, and audio
• Threading: Full conversation threading for discussions
• Bookmarks: Save posts for later reference
• Mobile Friendly: Responsive design works on all devices
• Open Source: Licensed under the AGPLv3

This guide walks through deploying Yarn.social on Klutch.sh using Docker, setting up your own pod, and joining the decentralized social network.

Why Deploy Yarn.social on Klutch.sh

Deploying Yarn.social on Klutch.sh provides several advantages for running your social media pod:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Yarn.social without complex orchestration. Push to GitHub, and your pod deploys automatically.

Persistent Storage: Attach persistent volumes for user data, posts, and media. Your community’s content survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for federation and secure user authentication.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your pod’s user count and activity level.

Environment Variable Management: Securely store sensitive configuration like secret keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your pod for a professional, branded experience.

Always-On Availability: Your social pod remains accessible 24/7 for users and federation partners.

Prerequisites

Before deploying Yarn.social on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A custom domain (recommended for production pods)
• Basic familiarity with Docker and containerization concepts

Understanding Yarn.social Architecture

Yarn.social is built as a monolithic Go application with integrated components:

Web Server: Serves the web interface and handles user interactions. Built with Go’s standard library and chi router.

Feed Manager: Handles twtxt feed parsing, caching, and aggregation from followed users across the network.

Media Handler: Processes uploaded images, videos, and audio with automatic transcoding and optimization.

Search Engine: Full-text search using Bleve, allowing users to search posts and users.

Task Queue: Background job processing for feed fetching, media processing, and maintenance tasks.

Data Store: Uses a combination of file-based storage and optional database backends.

Preparing Your Repository

To deploy Yarn.social on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

yarnsocial-deploy/
├── Dockerfile
├── config.yaml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM golang:1.21-alpine AS builder

# Install build dependencies
RUN apk add --no-cache git make gcc musl-dev

# Clone and build Yarn.social
WORKDIR /build
RUN git clone --depth 1 https://git.mills.io/yarnsocial/yarn.git .
RUN make build

FROM alpine:3.19

# Install runtime dependencies
RUN apk add --no-cache ca-certificates ffmpeg

# Create app user
RUN adduser -D -u 1000 yarn

# Create data directories
RUN mkdir -p /data /config && chown -R yarn:yarn /data /config

# Copy binary from builder
COPY --from=builder /build/yarnd /usr/local/bin/yarnd

# Copy configuration
COPY config.yaml /config/config.yaml

# Set user
USER yarn

# Set working directory
WORKDIR /data

# Environment variables
ENV YARND_DATA=/data
ENV YARND_CONFIG=/config/config.yaml

# Expose web port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8000/health || exit 1

# Start yarnd
CMD ["yarnd"]

Configuration File

Create a config.yaml file:

# Yarn.social Pod Configuration

# Pod Information
name: "My Yarn Pod"
description: "A friendly Yarn.social community"
store: "/data"

# Server Settings
bind: "0.0.0.0:8000"
base_url: "${BASE_URL}"

# Security
cookie_secret: "${COOKIE_SECRET}"
api_secret: "${API_SECRET}"

# Registration
open_registrations: true
register_email: ""

# Features
enable_email: false
enable_job_queue: true
enable_search: true

# Media Settings
max_upload_size: 16777216  # 16MB
media_resolution: 1280

# Federation
fetch_interval: "5m"
max_fetch_limit: 10000

# Appearance
theme: "auto"
lang: "en"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
BASE_URL	Yes	-	Public URL of your pod (e.g., https://yarn.example.com)
COOKIE_SECRET	Yes	-	Secret key for session cookies (32+ random characters)
API_SECRET	Yes	-	Secret key for API authentication
YARND_DATA	No	/data	Data storage directory
YARND_CONFIG	No	-	Path to configuration file

Deploying Yarn.social on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Generate Security Secrets

Generate secure random strings for your pod:

• Cookie Secret: 32+ character random string
• API Secret: 32+ character random string

You can generate these using any random string generator or password manager.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yaml .dockerignore
git commit -m "Initial Yarn.social pod configuration"
git remote add origin https://github.com/yourusername/yarnsocial-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. Name it something descriptive like “yarn-pod” or “social”.

Create a New App

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

Configure HTTP Traffic

Yarn.social serves its web interface over HTTP:

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
BASE_URL	https://your-app.klutch.sh (or your custom domain)
COOKIE_SECRET	Your generated cookie secret
API_SECRET	Your generated API secret

Attach Persistent Volumes

Persistent storage is essential for your pod:

Mount Path	Recommended Size	Purpose
/data	20 GB	User data, posts, and media files
/config	100 MB	Configuration files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Build the Yarn.social binary from source
• Create the container image
• Attach the persistent volumes
• Start the pod
• Provision an HTTPS certificate

Access Your Pod

Once deployment completes, access your Yarn.social pod at your deployment URL. Create your admin account by registering as the first user.

Initial Setup and Configuration

Creating Your Admin Account

The first user to register becomes the pod administrator:

1. Navigate to your pod URL
2. Click “Register” to create an account
3. Fill in your username, email, and password
4. Complete registration to become the admin

Pod Customization

Customize your pod through the admin settings:

1. Click your avatar and select “Settings”
2. Navigate to “Pod Settings” (admin only)
3. Customize the pod name, description, and rules
4. Upload a pod logo and favicon
5. Configure registration settings

Following Other Users

Start building your network:

1. Search for users by username or pod URL
2. Browse the “Discover” section for active users
3. Click “Follow” to add users to your timeline
4. Import follows from a twtxt.txt file

Federation Setup

Your pod automatically federates with others:

• Users can be followed using their full handle: user@pod.example.com
• Your posts are available to users on other pods
• Replies and mentions work across pod boundaries

Pod Administration

User Management

Manage your community members:

1. Access the admin panel from settings
2. View all registered users
3. Moderate content and manage permissions
4. Handle user reports and issues

Content Moderation

Keep your community healthy:

Feature	Description
Reporting	Users can report problematic content
Blocking	Block users from interacting with your pod
Muting	Mute users to hide their content
Content Rules	Set and enforce community guidelines

Backup and Maintenance

Regular maintenance tasks:

• Data Backup: Back up the /data volume regularly
• Log Rotation: Monitor and manage log file size
• Updates: Keep your pod updated with the latest version

Production Best Practices

Security Recommendations

• Strong Secrets: Use long, random strings for cookie and API secrets
• HTTPS Only: Always use HTTPS for production pods
• Registration Control: Consider invite-only registration for private communities
• Regular Updates: Keep your pod updated for security patches

Performance Optimization

• Media Settings: Configure appropriate upload size limits
• Fetch Intervals: Balance freshness with resource usage
• Caching: Enable caching for better performance
• Resource Allocation: Scale resources based on user activity

Federation Best Practices

• Domain Stability: Use a domain you control long-term
• Reliable Hosting: Ensure high uptime for federation partners
• Rate Limiting: Implement rate limiting to prevent abuse
• Pod Discovery: List your pod in pod directories

Troubleshooting Common Issues

Registration Not Working

Symptoms: Users cannot create accounts.

Solutions:

• Verify open_registrations is enabled in config
• Check cookie secret is properly set
• Confirm HTTPS is working correctly
• Review application logs for errors

Federation Issues

Symptoms: Cannot follow users on other pods or posts not appearing.

Solutions:

• Verify BASE_URL matches your actual URL
• Confirm HTTPS certificate is valid
• Check network connectivity to federation partners
• Review fetch interval settings

Media Upload Failures

Symptoms: Image or video uploads fail.

Solutions:

• Check available storage space on the volume
• Verify ffmpeg is installed for video processing
• Confirm upload size limits in configuration
• Review file permissions on data directory

Performance Issues

Symptoms: Pod is slow or unresponsive.

Solutions:

• Increase allocated CPU and memory
• Review and optimize fetch intervals
• Check for large media files consuming storage
• Consider cleaning old cached data

Additional Resources

• Yarn.social Official Website
• Yarn.social Git Repository
• Yarn.social Documentation
• twtxt Format Specification
• Yarn.social Pod Directory
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Yarn.social on Klutch.sh gives you a fully functional, decentralized social media pod that you control. The combination of Yarn.social’s federation capabilities and Klutch.sh’s deployment simplicity means you can join the decentralized social web without managing complex infrastructure.

With features like chronological feeds, cross-pod following, and multimedia support, Yarn.social provides a refreshing alternative to algorithmic social networks. Take control of your social media experience while connecting with a growing community of self-hosters.