Deploying Iceshrimp.NET

Introduction

Iceshrimp.NET is a next-generation Fediverse server that represents a complete rewrite of the original Iceshrimp project using .NET technologies. Built from the ground up with a focus on performance, stability, and maintainability, Iceshrimp.NET delivers a blazingly fast backend that can handle the demands of modern social networking while consuming significantly fewer resources than its JavaScript-based predecessors.

As a Fediverse server, Iceshrimp.NET implements the ActivityPub protocol, allowing your instance to communicate with millions of users across Mastodon, Misskey, Pleroma, and other compatible platforms. The result is a decentralized social network where you control your own data and community.

Key highlights of Iceshrimp.NET:

• Blazing Performance: .NET backend delivers exceptional speed and efficiency
• Resource Efficient: Significantly lower CPU and memory usage than Node.js alternatives
• ActivityPub Compatible: Federate with Mastodon, Misskey, Pleroma, and more
• Rich Features: Posts, reactions, quotes, custom emojis, and more
• Modern Interface: Clean, intuitive web UI for users and administrators
• Media Support: Images, videos, audio, and file attachments
• Search: Full-text search across posts and users
• Moderation Tools: Block lists, reports, and instance-level controls
• API Access: Compatible API for third-party clients
• Active Development: Ongoing improvements and feature additions
• Open Source: AGPL-3.0 licensed with community contributions

This guide walks through deploying Iceshrimp.NET on Klutch.sh using Docker, setting up your own presence on the Fediverse.

Why Deploy Iceshrimp.NET on Klutch.sh

Deploying Iceshrimp.NET on Klutch.sh provides several advantages for running a Fediverse instance:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Iceshrimp.NET without complex server configuration. Push to GitHub and your instance deploys automatically.

Persistent Storage: Attach persistent volumes for your database, media files, and configuration. Your posts, users, and uploads survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for ActivityPub federation which requires HTTPS.

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

Scalable Resources: Allocate CPU and memory based on your instance size. Start small for personal use and scale up as your community grows.

Custom Domains: Assign a custom domain for a professional, memorable instance address.

Reliable Federation: Consistent uptime ensures your instance remains connected to the Fediverse.

Prerequisites

Before deploying Iceshrimp.NET on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Iceshrimp.NET configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database (can be deployed separately)
• A custom domain (strongly recommended for federation)

Understanding Iceshrimp.NET Architecture

Iceshrimp.NET is built on modern .NET technologies:

ASP.NET Core Backend: The server application handles all ActivityPub communication, API requests, and business logic.

PostgreSQL Database: All data including users, posts, and federation state is stored in PostgreSQL.

Media Storage: Uploaded files can be stored locally or in S3-compatible object storage.

Background Jobs: Federated activities and maintenance tasks run asynchronously.

Preparing Your Repository

To deploy Iceshrimp.NET on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

iceshrimp-net-deploy/
├── Dockerfile
├── appsettings.json
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

# Install dependencies
RUN apt-get update && apt-get install -y \
    wget \
    git \
    && rm -rf /var/lib/apt/lists/*

# Clone and build Iceshrimp.NET
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

RUN git clone https://iceshrimp.dev/iceshrimp/iceshrimp.net.git .
RUN dotnet restore
RUN dotnet build -c Release -o /app/build

FROM build AS publish
RUN dotnet publish -c Release -o /app/publish

# Final image
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

# Create directories for data
RUN mkdir -p /app/data /app/media

# Set environment variables
ENV ASPNETCORE_URLS=http://+:5000
ENV ASPNETCORE_ENVIRONMENT=Production

# Copy configuration
COPY appsettings.json /app/appsettings.json

# Expose port
EXPOSE 5000

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

# Volumes
VOLUME ["/app/data", "/app/media"]

# Start the application
ENTRYPOINT ["dotnet", "Iceshrimp.NET.dll"]

Configuration File (appsettings.json)

Create an appsettings.json configuration file:

{
  "Instance": {
    "Name": "My Iceshrimp Instance",
    "Description": "A Fediverse server powered by Iceshrimp.NET",
    "Maintainer": "admin@example.com",
    "Domain": "your-domain.com"
  },
  "Database": {
    "Host": "your-postgres-host",
    "Port": 5432,
    "Database": "iceshrimp",
    "Username": "iceshrimp",
    "Password": "your-database-password"
  },
  "Media": {
    "StoragePath": "/app/media",
    "MaxFileSizeMB": 50
  },
  "Federation": {
    "Enabled": true
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Environment Variables Reference

Variable	Required	Default	Description
ASPNETCORE_URLS	No	http://+:5000	Application listen URL
ASPNETCORE_ENVIRONMENT	No	Production	Runtime environment
Database__Host	Yes	-	PostgreSQL hostname
Database__Port	No	5432	PostgreSQL port
Database__Database	Yes	-	Database name
Database__Username	Yes	-	Database username
Database__Password	Yes	-	Database password
Instance__Domain	Yes	-	Your instance domain
Instance__Name	No	Iceshrimp	Instance display name

Deploying Iceshrimp.NET on Klutch.sh

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

Set Up PostgreSQL

Iceshrimp.NET requires PostgreSQL. You can:

• Deploy a PostgreSQL app on Klutch.sh
• Use a managed database service like Neon or Supabase
• Use an existing PostgreSQL server

Create a database and user with full privileges.

Configure Your Domain

For proper federation, you’ll need a custom domain:

1. Register a domain or use an existing one
2. Point it to your Klutch.sh app after deployment
3. This domain becomes your instance’s permanent identity

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile appsettings.json .dockerignore
git commit -m "Initial Iceshrimp.NET deployment configuration"
git remote add origin https://github.com/yourusername/iceshrimp-net-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. Give it a descriptive name like “fediverse” or “iceshrimp”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Iceshrimp.NET Dockerfile.

Configure HTTP Traffic

Iceshrimp.NET serves its web interface over HTTP. In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
Database__Host	Your PostgreSQL hostname
Database__Database	iceshrimp
Database__Username	Database username
Database__Password	Database password
Instance__Domain	Your custom domain
Instance__Name	Your instance name

Attach Persistent Volumes

Persistent storage is essential for your instance. Add:

Mount Path	Recommended Size	Purpose
/app/data	10 GB	Application data and cache
/app/media	50+ GB	User-uploaded media files

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the Iceshrimp.NET container
• Attach the persistent volumes
• Start the application
• Provision an HTTPS certificate

Configure Custom Domain

After deployment:

1. Add your custom domain in Klutch.sh app settings
2. Update your domain’s DNS to point to Klutch.sh
3. Verify HTTPS is working

Complete Initial Setup

Access your instance and complete the initial setup:

1. Create your admin account
2. Configure instance settings
3. Set moderation policies
4. Start federating

Configuring Your Instance

Instance Settings

Configure your instance through the admin panel:

1. Instance Information: Name, description, and rules
2. Registration: Open, approval-required, or closed
3. Federation: Blocklists and allowlists
4. Media Settings: Upload limits and file types

Creating Users

Depending on your configuration:

• Open Registration: Users can sign up directly
• Invite-Only: Generate invite codes for new users
• Approval Required: Review and approve registration requests

Moderation

Iceshrimp.NET provides moderation tools:

• User suspensions and silencing
• Post deletions
• Instance-level blocks
• Report handling

Federation

How Federation Works

Your instance communicates with others via ActivityPub:

1. Users follow accounts on remote instances
2. Posts federate to followers’ instances
3. Replies, likes, and boosts propagate back
4. Local and federated timelines show relevant content

Managing Federation

Control which instances you federate with:

• Blocklist: Block problematic instances
• Allowlist: Only federate with approved instances
• Silence: Hide an instance from timelines without blocking

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Application fails to start with database errors.

Solutions:

• Verify PostgreSQL host is accessible
• Check username and password
• Ensure database exists
• Verify network connectivity

Federation Not Working

Symptoms: Cannot follow remote users, posts don’t federate.

Solutions:

• Verify HTTPS is properly configured
• Check domain configuration is correct
• Ensure WebFinger endpoint is accessible
• Review federation logs

Media Upload Failures

Symptoms: Cannot upload images or files.

Solutions:

• Check volume is properly mounted
• Verify disk space availability
• Review upload size limits

Additional Resources

• Iceshrimp.NET Repository
• Iceshrimp.NET GitHub Mirror
• ActivityPub Documentation
• Fediverse Information
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Iceshrimp.NET on Klutch.sh gives you a high-performance Fediverse instance with automatic builds, persistent storage, and secure HTTPS access essential for federation. The .NET backend delivers exceptional performance while consuming fewer resources than alternatives.

Whether you’re running a personal instance, building a community, or exploring the decentralized social web, Iceshrimp.NET on Klutch.sh provides the foundation for a reliable, performant presence on the Fediverse.