Skip to content
Klutch.sh Docs

Deploying Sourcehut

Introduction

Sourcehut (sr.ht) is a minimalist, privacy-focused software development platform that provides a complete suite of tools for open-source projects. Unlike feature-heavy platforms like GitHub or GitLab, Sourcehut embraces simplicity and focuses on workflows that have proven effective in major open-source projects like the Linux kernel.

Built with Python, Sourcehut consists of modular services that can be deployed independently or together. The platform prioritizes email-based workflows, mailing lists for code review, and a no-JavaScript interface that works in any browser.

Key highlights of Sourcehut:

  • Git Hosting (git.sr.ht): Repository hosting with web interface and SSH access
  • Mercurial Support (hg.sr.ht): Full Mercurial repository hosting
  • Mailing Lists (lists.sr.ht): Email-based discussions and patch submission
  • Issue Tracker (todo.sr.ht): Ticket tracking with email integration
  • CI/CD (builds.sr.ht): Continuous integration with build manifests
  • Paste Service (paste.sr.ht): Code snippet sharing
  • Wiki (man.sr.ht): Documentation hosting with Markdown support
  • Privacy-Focused: No tracking, minimal JavaScript, respects user privacy
  • Email-First Workflow: Supports email-based patch submission like kernel development
  • Federation Ready: Designed for decentralized deployment
  • 100% Open Source: Licensed under AGPLv3 with self-hosting encouraged

This guide walks through deploying Sourcehut’s core services on Klutch.sh using Docker.

Why Deploy Sourcehut on Klutch.sh

Deploying Sourcehut on Klutch.sh provides several advantages for hosting your own development platform:

Simplified Deployment: Klutch.sh handles the container orchestration, letting you focus on configuration.

Persistent Storage: Your repositories, issues, and CI artifacts persist across deployments.

HTTPS by Default: Automatic SSL certificates for secure access to all services.

GitHub Integration: Version control your Sourcehut configuration and automatically redeploy on updates.

Scalable Resources: Allocate resources based on your team size and repository count.

Environment Variable Management: Securely store database credentials and API keys.

Custom Domains: Use your own domain for a professional development platform.

High Availability: Keep your development infrastructure accessible around the clock.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • PostgreSQL database (can be deployed on Klutch.sh or external)
  • Redis instance for caching and queues
  • SMTP server for email functionality
  • Basic familiarity with Docker and software development workflows
  • (Optional) Custom domain with DNS control

Deploying Sourcehut on Klutch.sh

    Create a GitHub Repository

    Create a new GitHub repository for your Sourcehut deployment configuration.

    Create Your Dockerfile

    Create a Dockerfile for the meta.sr.ht service (user accounts and settings):

    FROM alpine:3.18
    

    # Install dependencies
    RUN apk add --no-cache \
        python3 \
        py3-pip \
        py3-psycopg2 \
        py3-bcrypt \
        py3-redis \
        git \
        postgresql-client
    

    # Install Sourcehut packages
    RUN pip3 install --break-system-packages \
        srht \
        metasrht
    

    # Create configuration directory
    RUN mkdir -p /etc/sr.ht
    

    # Copy configuration
    COPY config.ini /etc/sr.ht/config.ini
    

    # Expose the web interface port
    EXPOSE 5000
    

    # Set environment variables
    ENV SRHT_PATH=/etc/sr.ht
    

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

    CMD ["metasrht-web"]

    Create Configuration File

    Create a config.ini file with your Sourcehut settings:

    [sr.ht]
    site-name=Your Sourcehut Instance
    site-info=A self-hosted software development platform
    environment=production
    owner-name=Your Name
    owner-email=admin@example.com
    

    [meta.sr.ht]
    origin=https://meta.your-domain.com
    secret-key=${META_SECRET_KEY}
    

    [git.sr.ht]
    origin=https://git.your-domain.com
    repos=/var/lib/git
    

    [builds.sr.ht]
    origin=https://builds.your-domain.com
    

    [lists.sr.ht]
    origin=https://lists.your-domain.com
    

    [todo.sr.ht]
    origin=https://todo.your-domain.com
    

    [mail]
    smtp-host=${SMTP_HOST}
    smtp-port=${SMTP_PORT}
    smtp-user=${SMTP_USER}
    smtp-password=${SMTP_PASSWORD}
    smtp-from=noreply@your-domain.com
    

    [webhooks]
    private-key=/etc/sr.ht/webhook-private-key
    

    [objects]
    storage-directory=/var/lib/srht

    Push Your Repository to GitHub

    Commit and push your Dockerfile and configuration files.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “sourcehut” or similar.

    Create a New App

    Within your project, create a new app for the meta.sr.ht service. Connect your GitHub repository.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Configure the following environment variables:

    VariableValue
    META_SECRET_KEYA long random string for session security
    DATABASE_URLPostgreSQL connection string
    REDIS_URLRedis connection string
    SMTP_HOSTYour SMTP server hostname
    SMTP_PORTSMTP port (typically 587)
    SMTP_USERSMTP username
    SMTP_PASSWORDSMTP password

    Attach Persistent Volumes

    Add the following volumes:

    Mount PathRecommended SizePurpose
    /var/lib/git100 GBGit repository storage
    /var/lib/srht50 GBBuild artifacts and objects
    /var/log/srht10 GBApplication logs

    Deploy Your Application

    Click Deploy to build and start the Sourcehut service.

    Deploy Additional Services

    Repeat the deployment process for other Sourcehut services (git.sr.ht, builds.sr.ht, etc.) as needed, each in their own app within the project.

Service Architecture

Sourcehut consists of multiple independent services:

ServicePurposePort
meta.sr.htUser accounts and authentication5000
git.sr.htGit repository hosting5001
hg.sr.htMercurial repository hosting5002
builds.sr.htContinuous integration5003
lists.sr.htMailing lists5004
todo.sr.htIssue tracking5005
paste.sr.htCode snippets5006
man.sr.htWiki/documentation5007

Initial Configuration

Database Setup

Create databases for each service:

CREATE DATABASE metasrht;
CREATE DATABASE gitsrht;
CREATE DATABASE buildssrht;
CREATE DATABASE listssrht;
CREATE DATABASE todosrht;


CREATE USER srht WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE metasrht TO srht;
GRANT ALL PRIVILEGES ON DATABASE gitsrht TO srht;
GRANT ALL PRIVILEGES ON DATABASE buildssrht TO srht;
GRANT ALL PRIVILEGES ON DATABASE listssrht TO srht;
GRANT ALL PRIVILEGES ON DATABASE todosrht TO srht;

Creating Admin User

After deploying meta.sr.ht, create an admin account through the web interface or using the CLI tools.

Configuring Git Access

For SSH access to Git repositories, configure your SSH keys through the meta.sr.ht web interface.

Email Workflow Setup

Mailing List Configuration

Sourcehut’s mailing lists support email-based patch submission:

  1. Create a mailing list through lists.sr.ht
  2. Configure your email client to send patches
  3. Use git send-email for patch submission

Email Integration

Configure SMTP settings for:

  • Account verification emails
  • Password reset functionality
  • Mailing list delivery
  • Issue notifications

Continuous Integration

Build Manifests

Create .build.yml files in your repositories:

image: alpine/latest
packages:
  - python3
sources:
  - https://git.your-domain.com/~user/project
tasks:
  - test: |
      cd project
      python3 -m pytest

Build Runners

For CI functionality, deploy builds.sr.ht workers alongside the web service.

Troubleshooting

Service Won’t Start

  • Verify database connection strings are correct
  • Check that Redis is accessible
  • Review logs for configuration errors

Email Not Working

  • Confirm SMTP credentials are correct
  • Check that the SMTP server allows connections from your deployment
  • Verify from address is authorized

Repository Access Denied

  • Ensure SSH keys are properly configured
  • Check repository permissions
  • Verify the user has access to the repository

Additional Resources

Conclusion

Deploying Sourcehut on Klutch.sh gives you a powerful, privacy-focused software development platform that respects traditional open-source workflows. With its modular architecture, you can deploy only the services you need, starting with Git hosting and expanding to include mailing lists, CI/CD, and issue tracking. Whether you’re hosting personal projects or supporting a development team, Sourcehut on Klutch.sh provides a minimalist yet fully-featured alternative to mainstream development platforms.