Skip to content
Klutch.sh Docs

Deploying diaspora*

Introduction

diaspora* is a privacy-aware, distributed social network that gives users full ownership of their data and connections. Unlike centralized social networks, diaspora* operates as a federation of independently run servers called “pods,” allowing users to choose where their data lives while still connecting with the entire network.

The diaspora* project was one of the pioneers of decentralized social networking, launched in 2010 as a response to growing concerns about privacy on centralized platforms. Each pod operates independently but communicates with other pods using the diaspora* federation protocol, allowing users on different pods to follow, share, and interact with each other seamlessly.

Key highlights of diaspora*:

  • Decentralized Architecture: Choose your pod or run your own - your data stays where you want it
  • Aspects: Organize contacts into groups called “aspects” for granular sharing control
  • Federation Protocol: Connect with users across thousands of diaspora* pods worldwide
  • Data Ownership: Export your data or migrate to a different pod at any time
  • Privacy by Design: Share posts with specific aspects, not the entire world by default
  • Hashtag Discovery: Find and follow topics of interest across the federation
  • Mentions and Reshares: Familiar social networking features with privacy controls
  • No Advertising: Community-supported without tracking or targeted ads
  • 100% Open Source: AGPL-3.0 licensed with active community development

This guide walks through deploying a diaspora* pod on Klutch.sh, configuring federation, and managing your community.

Why Deploy diaspora* on Klutch.sh

Deploying diaspora* on Klutch.sh provides several advantages for running your own social network pod:

Simplified Deployment: Klutch.sh handles container orchestration, letting you focus on building your community rather than managing infrastructure.

Persistent Storage: Attach volumes for your database, user uploads, and configuration that persist across updates.

HTTPS by Default: Automatic SSL certificates are essential for federation security and user trust.

GitHub Integration: Connect your configuration repository for automated deployments.

Custom Domains: Use your own domain for a professional pod URL that represents your community.

Scalable Resources: Start small and scale up as your community grows.

Always-On Availability: Your pod remains accessible 24/7, essential for federation reliability.

Prerequisites

Before deploying diaspora* on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • A custom domain for your pod (highly recommended for federation)
  • Basic familiarity with Ruby on Rails applications
  • An SMTP server for sending emails (registration, notifications)
  • (Optional) A PostgreSQL database service

Understanding diaspora* Architecture

diaspora* uses a traditional web application architecture:

Ruby on Rails Backend: The core application handles user authentication, content management, and federation protocol.

PostgreSQL Database: Stores user data, posts, relationships, and federation information.

Redis Cache: Provides session storage and caching for improved performance.

Sidekiq Workers: Background job processing for federation, email delivery, and maintenance tasks.

Asset Pipeline: Serves compiled JavaScript, CSS, and image assets.

Federation Protocol: Communicates with other pods using the diaspora* federation protocol.

Preparing Your Repository

Create a GitHub repository with your diaspora* configuration.

Repository Structure

diaspora-deploy/
├── Dockerfile
├── config/
│   ├── diaspora.toml
│   └── database.yml
├── scripts/
│   └── entrypoint.sh
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for your diaspora* deployment:

FROM ruby:3.1-slim


# Install system dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    libssl-dev \
    libcurl4-openssl-dev \
    libxml2-dev \
    libxslt1-dev \
    imagemagick \
    nodejs \
    npm \
    git \
    curl \
    redis-server \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*


# Set working directory
WORKDIR /diaspora


# Clone diaspora
RUN git clone --depth 1 --branch master https://github.com/diaspora/diaspora.git .


# Install Ruby dependencies
RUN bundle config set --local deployment 'true' && \
    bundle config set --local without 'development test' && \
    bundle install


# Install Node.js dependencies
RUN npm install


# Precompile assets
RUN RAILS_ENV=production bundle exec rake assets:precompile


# Copy configuration
COPY config/diaspora.toml config/
COPY config/database.yml config/


# Copy entrypoint script
COPY scripts/entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh


# Create directories
RUN mkdir -p tmp/pids public/uploads log


# Expose port
EXPOSE 3000


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


ENTRYPOINT ["/entrypoint.sh"]
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]

Creating Configuration Files

Create config/diaspora.toml:

[configuration]


[configuration.environment]
url = "https://your-pod.example.com"
certificate_authorities = "/etc/ssl/certs/ca-certificates.crt"


[configuration.server]
rails_environment = "production"
listen = "0.0.0.0"
port = 3000


[configuration.settings]
pod_name = "Your Pod Name"
enable_registrations = true
autofollow_on_join = true
autofollow_on_join_user = "admin"


[configuration.settings.invitations]
open = true
count = 25


[configuration.privacy]
google_analytics_key = ""
piwik.enable = false
statistics.user_counts = true
statistics.post_counts = true


[configuration.services]
# Configure social service integrations here


[configuration.mail]
enable = true
sender_address = "no-reply@your-pod.example.com"
method = "smtp"


[configuration.mail.smtp]
host = "smtp.example.com"
port = 587
authentication = "plain"
username = "your-smtp-username"
password = "your-smtp-password"
starttls_auto = true
openssl_verify_mode = "peer"


[configuration.admins]
account = "admin"
podmin_email = "admin@example.com"

Create config/database.yml:

production:
  adapter: postgresql
  host: <%= ENV['DATABASE_HOST'] %>
  port: <%= ENV['DATABASE_PORT'] || 5432 %>
  username: <%= ENV['DATABASE_USERNAME'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>
  database: <%= ENV['DATABASE_NAME'] || 'diaspora_production' %>
  pool: 25
  encoding: unicode

Creating the Entrypoint Script

Create scripts/entrypoint.sh:

#!/bin/bash
set -e


# Start Redis in background
redis-server --daemonize yes


# Wait for PostgreSQL
until pg_isready -h "$DATABASE_HOST" -p "${DATABASE_PORT:-5432}" -U "$DATABASE_USERNAME"; do
  echo "Waiting for PostgreSQL..."
  sleep 2
done


# Run database migrations
bundle exec rake db:migrate


# Start Sidekiq in background
bundle exec sidekiq -d -L log/sidekiq.log


# Execute main command
exec "$@"

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store
log/
tmp/
public/uploads/

Deploying diaspora* on Klutch.sh

Follow these steps to deploy your diaspora* pod:

    Set Up a PostgreSQL Database

    diaspora* requires PostgreSQL. You can either:

    • Use a managed PostgreSQL service
    • Deploy PostgreSQL as a separate Klutch.sh app

    Note the database connection details for environment variables.

    Configure Your Domain

    Update diaspora.toml with your actual domain. This is critical as it cannot be changed after federation begins.

    Configure Email Settings

    Update the SMTP settings in diaspora.toml with your email provider details. diaspora* requires email for user registration and notifications.

    Push Your Repository to GitHub

    Initialize and push your configuration:

    Terminal window
    git init
    git add .
    git commit -m "Initial diaspora* configuration"
    git remote add origin https://github.com/yourusername/diaspora-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 for your diaspora* pod.

    Create a New App

    Create a new app within your project and connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    DATABASE_HOSTYour PostgreSQL host
    DATABASE_PORT5432 (or your port)
    DATABASE_USERNAMEDatabase username
    DATABASE_PASSWORDDatabase password
    DATABASE_NAMEdiaspora_production
    SECRET_KEY_BASEGenerate with openssl rand -hex 64
    RAILS_ENVproduction

    Attach Persistent Volumes

    Add persistent volumes for your pod:

    Mount PathRecommended SizePurpose
    /diaspora/public/uploads50 GBUser-uploaded images and files
    /diaspora/log5 GBApplication logs

    Configure Custom Domain

    Add your custom domain in Klutch.sh and configure DNS:

    • A record pointing to your Klutch.sh IP
    • Verify SSL certificate is provisioned

    Deploy Your Application

    Click Deploy to build and start your diaspora* pod.

    Create Admin Account

    Once deployed, register the first user account. This should match the autofollow_on_join_user in your configuration to become the pod admin.

Initial Setup and Configuration

Creating the Admin Account

After deployment, register an account with the username specified in configuration.settings.autofollow_on_join_user. This account will have administrative privileges.

Configuring Pod Settings

Access the admin panel at https://your-pod.example.com/admins/dashboard:

  • Review pod statistics
  • Manage user accounts
  • Configure federation settings
  • Monitor background jobs

Joining the Federation

Your pod automatically discovers and connects with other pods through:

  1. User follows and interactions
  2. Hashtag federation
  3. Manual pod additions

Check federation status in the admin dashboard.

Managing Your Community

User Registration

Control registration through diaspora.toml:

[configuration.settings]
enable_registrations = true  # Enable/disable open registration


[configuration.settings.invitations]
open = true     # Allow users to send invitations
count = 25      # Invitations per user

Content Moderation

As a pod admin, you can:

  • Review reported content
  • Suspend or delete user accounts
  • Block problematic pods from federation
  • Set community guidelines

Pod Rules and Guidelines

Establish community guidelines for your pod:

  1. Create a public post with your pod rules
  2. Pin it to your profile
  3. Reference it in registration forms
  4. Enforce consistently

Federation Management

Understanding Federation

diaspora* federation means:

  • Users on your pod can follow users on other pods
  • Posts with public visibility are shared across pods
  • Hashtags aggregate content from federated pods

Pod Blocking

Block problematic pods if necessary:

# In Rails console
Pod.find_by(host: "problematic-pod.example.com").update(blocked: true)

Monitoring Federation Health

Check federation status:

  • Review Sidekiq job queues for delivery failures
  • Monitor federation logs for errors
  • Check pod connectivity in the admin dashboard

Aspects and Privacy

Understanding Aspects

Aspects are diaspora*‘s core privacy feature:

  • Aspects are groups of contacts you define (Family, Work, Friends)
  • Posts are shared to specific aspects not publicly by default
  • Users control who sees their content at a granular level

Default Aspects

diaspora* creates default aspects:

  • Family
  • Friends
  • Work
  • Acquaintances

Users can create custom aspects for their needs.

Visibility Options

When posting, users choose visibility:

VisibilityDescription
All aspectsVisible to all contacts
PublicVisible to everyone, federated
Specific aspectsOnly visible to selected groups

Production Best Practices

Performance Optimization

  • Database Indexing: Ensure PostgreSQL indexes are optimized
  • Redis Caching: Monitor Redis memory usage
  • Sidekiq Workers: Scale workers based on federation load
  • Asset Caching: Enable CDN for static assets

Security Recommendations

  • Strong Secrets: Use cryptographically random secrets
  • Regular Updates: Keep diaspora* updated for security patches
  • Database Backups: Implement regular PostgreSQL backups
  • SSL/TLS: Ensure HTTPS is always enforced

Backup Strategy

Regular backups should include:

  1. PostgreSQL database dump
  2. User uploads in /diaspora/public/uploads
  3. Configuration files
  4. Redis data (for session persistence)

Troubleshooting Common Issues

Federation Not Working

Symptoms: Cannot follow users on other pods.

Solutions:

  • Verify your pod URL is correctly configured
  • Check SSL certificate is valid
  • Ensure Sidekiq workers are running
  • Review federation logs for errors

Sidekiq Jobs Failing

Symptoms: Background jobs accumulating in queues.

Solutions:

  • Check Sidekiq logs for error messages
  • Verify Redis connection is stable
  • Ensure sufficient memory for workers
  • Restart Sidekiq if needed

Email Not Sending

Symptoms: Users not receiving registration emails.

Solutions:

  • Verify SMTP credentials are correct
  • Check firewall allows SMTP connections
  • Review mail logs for delivery errors
  • Test SMTP connection manually

Slow Performance

Symptoms: Pages load slowly or timeout.

Solutions:

  • Increase container resources
  • Optimize database queries
  • Check Redis cache hit rates
  • Review and address slow Sidekiq jobs

Additional Resources

Conclusion

Deploying diaspora* on Klutch.sh lets you run your own node in a global, privacy-respecting social network. The combination of diaspora*‘s federation protocol and Klutch.sh’s container management means you can provide your community with a social networking experience that respects their privacy and data ownership.

With aspects for granular sharing control, federation for connecting with the broader diaspora* network, and complete data ownership, your pod gives users an alternative to centralized social media platforms. Whether you’re building a community for friends, an organization, or a special interest group, diaspora* on Klutch.sh provides the foundation for social networking on your own terms.