Deploying GoToSocial

Introduction

GoToSocial is a lightweight, customizable, and safety-focused ActivityPub social network server written in Go. Designed as a Mastodon-compatible alternative for small instances and single-user deployments, GoToSocial provides a fast, resource-efficient way to join the Fediverse without the overhead of larger platforms.

Built with privacy and safety at its core, GoToSocial is perfect for running on low-powered devices like single-board computers or repurposed laptops. The server focuses on providing essential social networking features while maintaining excellent performance and minimal resource consumption.

Key highlights of GoToSocial:

Lightweight Design: Runs efficiently on minimal hardware, including Raspberry Pi
ActivityPub Federation: Full compatibility with Mastodon, Pleroma, Misskey, and other Fediverse servers
Safety-Focused: Granular blocklist controls and federation management
SQLite or PostgreSQL: Flexible database options for different deployment sizes
Mastodon API Compatible: Works with existing Mastodon clients and apps
Built-in Let’s Encrypt: Automatic HTTPS certificate management
Two-Factor Authentication: TOTP-based 2FA for account security
Media Handling: Efficient media processing and storage
Single Binary: Easy deployment with a single executable
100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying GoToSocial on Klutch.sh using Docker, configuring federation settings, and setting up your Fediverse presence.

Why Deploy GoToSocial on Klutch.sh

Deploying GoToSocial on Klutch.sh provides several advantages for running a Fediverse server:

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

Persistent Storage: Attach persistent volumes for your database and media files. Posts, accounts, and uploads survive container restarts.

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

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

Scalable Resources: Allocate CPU and memory based on your instance size and activity level.

Custom Domains: Assign a custom domain for your Fediverse identity.

Always-On Availability: Your social network remains accessible 24/7 for federation and user access.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your GoToSocial configuration
A custom domain (highly recommended for federation)
Basic familiarity with Docker and containerization concepts
(Optional) SMTP credentials for email notifications

Understanding GoToSocial Architecture

GoToSocial is built for simplicity and efficiency:

Go Backend: Written in Go for excellent performance and low resource usage.

Database Options: Supports SQLite for small instances or PostgreSQL for larger deployments.

ActivityPub Protocol: Implements the W3C ActivityPub standard for federation with other Fediverse servers.

Mastodon API: Provides Mastodon-compatible API endpoints, enabling use with existing Mastodon clients.

Media Processing: Built-in image and video processing with configurable storage backends.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM superseriousbusiness/gotosocial:latest

# Set environment variables
ENV GTS_HOST=${GTS_HOST}
ENV GTS_ACCOUNT_DOMAIN=${GTS_ACCOUNT_DOMAIN}
ENV GTS_PROTOCOL=https
ENV GTS_PORT=8080
ENV GTS_DB_TYPE=sqlite
ENV GTS_DB_ADDRESS=/gotosocial/storage/sqlite.db

# Expose the web interface port
EXPOSE 8080

# The base image includes the default entrypoint

Advanced Dockerfile with PostgreSQL

For larger instances using PostgreSQL:

FROM superseriousbusiness/gotosocial:latest

# Instance Configuration
ENV GTS_HOST=${GTS_HOST}
ENV GTS_ACCOUNT_DOMAIN=${GTS_ACCOUNT_DOMAIN}
ENV GTS_PROTOCOL=https
ENV GTS_PORT=8080

# Database Configuration (PostgreSQL)
ENV GTS_DB_TYPE=postgres
ENV GTS_DB_ADDRESS=${GTS_DB_ADDRESS}
ENV GTS_DB_PORT=${GTS_DB_PORT:-5432}
ENV GTS_DB_USER=${GTS_DB_USER}
ENV GTS_DB_PASSWORD=${GTS_DB_PASSWORD}
ENV GTS_DB_DATABASE=${GTS_DB_DATABASE}

# Storage Configuration
ENV GTS_STORAGE_LOCAL_BASE_PATH=/gotosocial/storage

# SMTP Configuration (optional)
ENV GTS_SMTP_HOST=${GTS_SMTP_HOST}
ENV GTS_SMTP_PORT=${GTS_SMTP_PORT:-587}
ENV GTS_SMTP_USERNAME=${GTS_SMTP_USERNAME}
ENV GTS_SMTP_PASSWORD=${GTS_SMTP_PASSWORD}
ENV GTS_SMTP_FROM=${GTS_SMTP_FROM}

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

# Expose the application port
EXPOSE 8080

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
`GTS_HOST`	Yes	-	The hostname of your instance (e.g., `social.example.com`)
`GTS_ACCOUNT_DOMAIN`	No	Same as GTS_HOST	Domain for user accounts if different from host
`GTS_PROTOCOL`	No	https	Protocol (https recommended)
`GTS_PORT`	No	8080	Port to listen on
`GTS_DB_TYPE`	No	sqlite	Database type (sqlite or postgres)
`GTS_DB_ADDRESS`	Yes*	-	Database path (SQLite) or host (PostgreSQL)
`GTS_DB_PORT`	No	5432	PostgreSQL port
`GTS_DB_USER`	Yes*	-	PostgreSQL username
`GTS_DB_PASSWORD`	Yes*	-	PostgreSQL password
`GTS_DB_DATABASE`	Yes*	-	PostgreSQL database name
`GTS_SMTP_HOST`	No	-	SMTP server hostname
`GTS_SMTP_PORT`	No	587	SMTP server port
`GTS_SMTP_USERNAME`	No	-	SMTP username
`GTS_SMTP_PASSWORD`	No	-	SMTP password
`GTS_SMTP_FROM`	No	-	From address for emails

*Required for PostgreSQL deployments

Deploying GoToSocial on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

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 GoToSocial Dockerfile.

Configure HTTP Traffic

GoToSocial serves its web interface and API over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
`GTS_HOST`	`your-app-name.klutch.sh` (or your custom domain)
`GTS_PROTOCOL`	`https`
`GTS_DB_TYPE`	`sqlite`
`GTS_DB_ADDRESS`	`/gotosocial/storage/sqlite.db`

For PostgreSQL, add database credentials. See the PostgreSQL deployment guide for setting up a database.

Attach Persistent Volumes

Persistent storage is essential for GoToSocial. Add the following volume:

Mount Path	Recommended Size	Purpose
`/gotosocial/storage`	50 GB	Database (SQLite), media files, and cache

Deploy Your Application

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

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the GoToSocial container
Provision an HTTPS certificate

Create Your Admin Account

After deployment, create your first account using the CLI. Access the container and run:

gotosocial admin account create \
  --username your_username \
  --email your@email.com \
  --password your_secure_password

Then promote to admin:

gotosocial admin account promote --username your_username

Access GoToSocial

Once deployment completes, access your GoToSocial instance at https://your-app-name.klutch.sh. Log in with your created account.

Initial Setup and Configuration

Using Mastodon Clients

GoToSocial is compatible with Mastodon clients. Popular options include:

Web: Use the built-in web interface or Phanpy, Pinafore, Elk
iOS: Toot!, Ice Cubes, Mona
Android: Tusky, Fedilab, Megalodon
Desktop: Whalebird, Sengi, Tuba

Configure your client with your GoToSocial instance URL and log in with your account.

Federation Settings

Configure how your instance federates with others:

Access the admin settings panel
Navigate to Federation settings
Configure:
- Federation mode: Allow/deny lists for other instances
- Blocklists: Import community blocklists for safety
- Allowlists: Restrict federation to specific instances

Instance Customization

Personalize your GoToSocial instance:

Instance name: Set a display name for your server
Instance description: Describe your instance’s purpose
Terms of service: Define your instance rules
Custom CSS: Style the web interface
Banner/Avatar: Add instance branding

Using a Custom Domain

For proper Fediverse identity, use a custom domain:

Add your domain to Klutch.sh
Configure DNS to point to your Klutch.sh app
Update GTS_HOST to your custom domain
Redeploy the application

Important: Once you set a domain and start federating, changing it is difficult. Choose carefully.

Security Best Practices

Account Security

Strong Passwords: Use unique, strong passwords for all accounts
Two-Factor Authentication: Enable TOTP 2FA for all accounts
Regular Audits: Review account activity and federation logs

Federation Safety

Blocklists: Subscribe to community-maintained blocklists
Moderation: Monitor federated content and block problematic instances
Rate Limiting: Configure rate limits to prevent abuse

Instance Security

Regular Updates: Keep GoToSocial updated for security patches
Backup Strategy: Regularly back up the database and media files
Monitoring: Watch for unusual activity or resource usage

Troubleshooting Common Issues

Federation Not Working

Symptoms: Cannot follow users on other instances.

Solutions:

Verify HTTPS is working correctly
Check GTS_HOST matches your actual domain
Ensure your domain resolves correctly
Verify .well-known/webfinger endpoint is accessible
Check federation logs for errors

Media Upload Failures

Symptoms: Cannot upload images or media.

Solutions:

Verify storage volume is mounted correctly
Check available disk space
Review file size limits
Check file type restrictions

Account Creation Issues

Symptoms: Cannot create accounts via CLI.

Solutions:

Ensure database is accessible
Check database permissions
Verify storage directory is writable
Review application logs for errors

Client Connection Problems

Symptoms: Mastodon clients cannot connect.

Solutions:

Verify API endpoints are accessible
Check OAuth configuration
Ensure HTTPS certificate is valid
Try a different client to isolate the issue

Updating GoToSocial

To update to a newer version:

Back Up Data: Export your database and media files
Update Dockerfile: Change the image tag to the new version
Push Changes: Commit and push to trigger redeployment
Verify: Test federation and functionality after update

GoToSocial maintains backward compatibility within minor versions. Review release notes before major upgrades.

Additional Resources

Conclusion

Deploying GoToSocial on Klutch.sh gives you a lightweight, efficient gateway to the Fediverse. The combination of GoToSocial’s minimal resource requirements and Klutch.sh’s deployment simplicity means you can run your own social network without managing complex infrastructure.

With ActivityPub federation, Mastodon client compatibility, and safety-focused features, GoToSocial provides everything you need for a personal or small community Fediverse presence. Whether you’re running a single-user instance or a small community server, GoToSocial on Klutch.sh delivers reliable, always-available social networking on your terms.