How to Self-Host GoToSocial with Docker Compose

The Lightweight Fediverse Option

If Mastodon is the SUV of the fediverse, GoToSocial is the motorcycle. It’s a single Go binary that federates with the entire ActivityPub network — Mastodon, Pleroma, Misskey, Pixelfed — while using a fraction of the resources. No PostgreSQL required (SQLite by default), no Redis, no Sidekiq. One container, one port, done. Official site

GoToSocial is still in beta (targeting v1.0 in late 2026), but it’s stable enough for daily use. The trade-off: it doesn’t have its own web interface for posting. You use any Mastodon-compatible client (Tusky, Ivory, Megalodon, Semaphore) to interact with your account.

Prerequisites

• A Linux server (Ubuntu 22.04+ or any Docker host)
• Docker and Docker Compose installed (guide)
• 512 MB RAM (yes, really)
• 5 GB of free disk space
• A domain name pointing to your server

Requirement	Minimum	Recommended
CPU	1 core	2 cores
RAM	256 MB	512 MB
Disk	2 GB	10 GB
Email	Optional	SMTP for notifications

Docker Compose Configuration

services:
  gotosocial:
    image: superseriousbusiness/gotosocial:0.20.1
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - gotosocial-data:/gotosocial/storage
    environment:
      ## REQUIRED — your instance domain
      GTS_HOST: social.example.com

      ## Protocol — set to https if using a reverse proxy with SSL
      GTS_PROTOCOL: https

      ## Database — SQLite by default, no external DB needed
      GTS_DB_TYPE: sqlite
      GTS_DB_ADDRESS: /gotosocial/storage/sqlite.db

      ## Instance settings
      GTS_INSTANCE_EXPOSE_PEERS: "false"
      GTS_INSTANCE_EXPOSE_SUSPENDED: "false"
      GTS_INSTANCE_EXPOSE_SUSPENDED_WEB: "false"
      GTS_INSTANCE_DELIVER_TO_SHARED_INBOXES: "true"

      ## Accounts — disable open registration by default
      GTS_ACCOUNTS_REGISTRATION_OPEN: "false"

      ## Media — remote media cache settings
      GTS_MEDIA_REMOTE_CACHE_DAYS: 7

      ## SMTP (optional but recommended for notifications)
      # GTS_SMTP_HOST: smtp.example.com
      # GTS_SMTP_PORT: 587
      # GTS_SMTP_USERNAME: your_smtp_user
      # GTS_SMTP_PASSWORD: your_smtp_password
      # GTS_SMTP_FROM: [email protected]

      ## Advanced — Let's Encrypt (only if NOT behind a reverse proxy)
      # GTS_LETSENCRYPT_ENABLED: "true"
      # GTS_LETSENCRYPT_EMAIL: [email protected]

      TZ: UTC
    user: "1000:1000"
    networks:
      - gotosocial

networks:
  gotosocial:

volumes:
  gotosocial-data:

Using PostgreSQL Instead of SQLite

For instances with more than a few dozen active users, PostgreSQL performs better. Add it to your Compose file:

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - postgres-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: gotosocial
      POSTGRES_USER: gotosocial
      POSTGRES_PASSWORD: change_this_password
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "gotosocial"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - gotosocial

  gotosocial:
    # ... same as above, but change DB settings:
    environment:
      GTS_DB_TYPE: postgres
      GTS_DB_ADDRESS: db
      GTS_DB_PORT: 5432
      GTS_DB_USER: gotosocial
      GTS_DB_PASSWORD: change_this_password
      GTS_DB_DATABASE: gotosocial
    depends_on:
      db:
        condition: service_healthy

volumes:
  postgres-data:

Start the stack:

docker compose up -d

Initial Setup

GoToSocial doesn’t have a web-based setup wizard. Create your admin account via the command line:

# Create an admin user
docker compose exec gotosocial /gotosocial/gotosocial admin account create \
  --username admin \
  --email [email protected] \
  --password YourSecurePassword123

# Promote to admin
docker compose exec gotosocial /gotosocial/gotosocial admin account promote \
  --username admin

Then log in using any Mastodon-compatible client:

1. Open Tusky, Ivory, Megalodon, or Semaphore
2. Enter your instance domain (social.example.com)
3. Authorize the app via the browser
4. You’re on the fediverse

Configuration

GoToSocial is configured entirely through environment variables (or a config.yaml file). Key settings:

Variable	Purpose	Default
GTS_HOST	Instance domain (cannot change later)	Required
GTS_PROTOCOL	http or https	https
GTS_ACCOUNTS_REGISTRATION_OPEN	Allow public signups	true
GTS_ACCOUNTS_APPROVAL_REQUIRED	Require admin approval	true
GTS_MEDIA_REMOTE_CACHE_DAYS	Days to keep remote media	7
GTS_MEDIA_IMAGE_MAX_SIZE	Max upload size in bytes	10485760 (10 MB)
GTS_INSTANCE_LANGUAGES	Instance languages	["en"]
GTS_ADVANCED_RATE_LIMIT_REQUESTS	API rate limit per 5 min	300

Instance Settings via Admin Panel

GoToSocial has a web-based admin panel at https://social.example.com/settings. From there you can:

• Set instance title, description, and contact info
• Manage domain blocks and allows
• View federation status
• Manage user accounts
• Configure custom emoji

Reverse Proxy

GoToSocial listens on port 8080. Place it behind a reverse proxy for HTTPS.

Caddy:

social.example.com {
    reverse_proxy localhost:8080
}

Nginx Proxy Manager: Add a new proxy host pointing to localhost:8080 with SSL enabled.

GoToSocial also has built-in Let’s Encrypt support — set GTS_LETSENCRYPT_ENABLED=true and expose port 80 directly if you don’t want a separate reverse proxy.

See our Reverse Proxy Setup guide for detailed instructions.

Backup

GoToSocial stores everything in the data volume:

• SQLite database: /gotosocial/storage/sqlite.db
• Media uploads: /gotosocial/storage/

# Stop the container for a clean backup
docker compose stop gotosocial

# Back up the entire data volume
docker run --rm -v gotosocial-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/gotosocial_backup_$(date +%F).tar.gz -C /data .

# Restart
docker compose start gotosocial

If using PostgreSQL, also dump the database:

docker compose exec db pg_dump -U gotosocial gotosocial > gotosocial_db_$(date +%F).sql

See our Backup Strategy guide.

Troubleshooting

Can’t Find Users on Other Instances

Symptom: Searching for @[email protected] returns nothing. Fix: GoToSocial needs outbound HTTPS access to federate. Check that your server can reach other instances. Verify your domain’s DNS is correct and your reverse proxy is forwarding requests properly. Check logs: docker compose logs gotosocial | grep -i error.

Client Authorization Fails

Symptom: Mastodon client redirects to login but never completes. Fix: Ensure GTS_HOST exactly matches your domain (no trailing slash, no port number). The protocol must match your actual setup — https if behind a reverse proxy with SSL. Check that your reverse proxy passes Host and X-Forwarded-Proto headers.

Media Uploads Fail

Symptom: “Could not process media” when uploading images. Fix: Check volume permissions. GoToSocial runs as UID 1000 by default:

sudo chown -R 1000:1000 /var/lib/docker/volumes/gotosocial-data/_data/

High Disk Usage

Symptom: Storage growing rapidly from federated media. Fix: Reduce GTS_MEDIA_REMOTE_CACHE_DAYS to clean up cached remote media faster. Run media cleanup manually:

docker compose exec gotosocial /gotosocial/gotosocial admin media prune --remote-cache-days 3

Resource Requirements

Resource	Single User	Small Instance (5-10 users)
RAM	100-150 MB	200-400 MB
CPU	Negligible	Low
Disk	1-2 GB	5-20 GB
Bandwidth	1-5 GB/month	10-30 GB/month

GoToSocial is remarkably efficient. A single-user instance runs comfortably on a $3/month VPS or even a Raspberry Pi. It’s the lightest way to join the fediverse with your own domain.

Verdict

GoToSocial is the best choice for personal fediverse instances and small communities that don’t need Mastodon’s feature weight. The “no web UI for posting” limitation sounds worse than it is — Mastodon-compatible clients are excellent, and you probably use a native app for social media anyway.

Choose GoToSocial if you want a personal fediverse presence with minimal server resources. It’s perfect for single-user instances, Raspberry Pi deployments, or anyone who finds Mastodon too heavy.

Look elsewhere if you need a full-featured community platform with a web interface, moderation tools, and Elasticsearch search. Mastodon is the right choice for that. If you want something between GoToSocial and Mastodon in terms of features and resource usage, consider Pleroma.

FAQ

Is GoToSocial compatible with Mastodon?

Yes. GoToSocial implements the Mastodon Client API, so most Mastodon clients work. It also federates with Mastodon, Pleroma, Misskey, Pixelfed, and other ActivityPub servers. Some advanced Mastodon features (like polls and scheduled posts) may not be fully supported yet.

Can I migrate from Mastodon to GoToSocial?

Not directly — there’s no built-in migration tool. However, you can use Mastodon’s account migration feature to move your followers to a GoToSocial account on the same or different domain. Posts don’t transfer.

When will GoToSocial reach v1.0?

The developers are targeting late 2026 for a v1.0 release. The project received NLnet NGI Zero funding for 2026 development. Despite the beta label, it’s stable for daily use.

Does GoToSocial support custom emoji?

Yes. Upload custom emoji through the admin panel at /settings. They federate to other instances automatically.

Related

• Mastodon vs GoToSocial
• How to Self-Host Mastodon
• How to Self-Host Pleroma
• Best Self-Hosted Social Networks
• Best Fediverse Software
• Replace Twitter
• The Fediverse Explained
• Reverse Proxy Setup
• Docker Compose Basics