How to Use GoToSocial: The Beginner's Guide (First Deploy, First Admin, the Client Lesson, and the Federation Rule)

CodexFuse Team · 2026-11-01T16:00:00.000Z · 13 min read min read

How to use GoToSocial: a complete beginner's guide to the lightweight self-hosted Fediverse server — Docker Compose deploy, the domain-is-forever rule, first admin, client apps, federation, moderation, and backups.

Learning how to use GoToSocial is the shortest path to owning your own corner of the Fediverse. GoToSocial is a lightweight, self-hosted ActivityPub server — you run it on your own hardware, pick your own domain, and talk to the whole Fediverse (Mastodon, Pixelfed, and friends) without a big-company account in the middle. This GoToSocial tutorial runs the complete beginner arc in one place: choosing where your instance lives, deploying it with Docker Compose, the domain-is-forever rule, creating your first admin, picking a client app (the client lesson), following your first remote account (the federation rule), moderation basics, and the backup rule that protects your identity. If you have never touched Docker, start with our Docker beginner guide — everything below assumes you can run one compose file.

What Is GoToSocial?

GoToSocial is a lightweight, customizable, safety-focused ActivityPub social network server written in Go. That is the project's own description, and every word carries weight: ActivityPub means it speaks the same protocol as Mastodon, so you can follow and be followed across the whole Fediverse; lightweight means it is designed for small or single-user instances on low-powered devices — old laptops repurposed as home servers, a tiny VPS, even a single-board computer; safety-focused means it ships with sensible defaults like a default blocklist federation mode and private-by-default visibility. Two honest facts frame everything else in this guide: GoToSocial is still pre-1.0 (the current release is v0.22.0 "Shrubby Sloth," released June 29, 2026), and there is no flagship instance to join — the entire point is that you run your own.

GoToSocial vs Mastodon: Who Should Pick Which

Every beginner asks this, so here is the one-paragraph answer before the table: pick GoToSocial when you want your own social home for yourself or a small group on hardware you control, and pick Mastodon when you need a big-community server, an official mobile app, and a mature feature set. GoToSocial is explicitly "not designed for 'must-follow' influencers with tens of thousands of followers" — it is a small-home product, not a broadcast product. It keeps full Mastodon API compatibility, which is the clever part: any client that talks to Mastodon also talks to GoToSocial.

The short version: GoToSocial is the single-user Mastodon alternative for people who want the Fediverse without running a Mastodon-shaped machine.

How Do You Use GoToSocial? The 8-Step Short Version

If you want the whole arc before the detail, this is how to use GoToSocial from zero to your first federated post:

1. Pick a domain you will keep forever — your Fediverse identity is bound to it.
2. Choose where it runs: a home server on your LAN or a cheap VPS.
3. Deploy with Docker Compose: one container, SQLite, GoToSocial listens on port 8080.
4. Create your first admin account with the CLI and promote it, then restart the container.
5. Open the settings panel at https://your-domain/settings and configure the basics.
6. Install a client app — Pinafore in the browser, Tusky on Android, Feditext on iOS — and log in.
7. Follow your first remote account by pasting its @user@domain handle into your client's search.
8. Back up sqlite.db — it holds your signing keys, and without it your identity is gone.

Step 1: Choose Where Your Instance Lives (and the Domain-Is-Forever Rule)

Before anything else, pick your domain, and pick it like a tattoo: once your instance federates from a domain, your identity, your followers, and your cryptographic signing keys are bound to that name. The official docs are blunt — lose your database and its keys and you can never federate from that domain again — so a domain you might abandon is worse than no domain. Use a subdomain you control (social.example.com works fine) and never plan to rename it.

Then decide where it runs. A home server costs nothing monthly and keeps your data on your LAN; the only tradeoff is reachability — you need port 443 open or a tunnel for federation to find you. A cheap VPS (any small instance with Docker) gives you a public IP and uptime for a few dollars a month; read what VPS hosting actually is before renting one. If your server stays at home but you want access without opening ports, our Tailscale beginner guide covers the private-access lane — though federation itself still needs a public HTTPS endpoint.

Step 2: Deploy GoToSocial With Docker Compose

The Docker install is the officially documented beginner path, and it is deliberately simple: one container, a SQLite database file, and environment variables instead of a config file. (Binary installs copy example/config.yaml instead, but the compose path skips that entirely.) GoToSocial listens on port 8080 inside the container, and the official example maps host 443 to it so federation works over HTTPS.

services:
  gotosocial:
    image: docker.io/superseriousbusiness/gotosocial:0.22.0
    container_name: gotosocial
    restart: always
    user: 1000:1000
    networks:
      - gotosocial
    ports:
      - "443:8080"
    environment:
      GTS_HOST: social.example.com
      GTS_DB_TYPE: sqlite
      GTS_DB_ADDRESS: /gotosocial/storage/sqlite.db
      GTS_LETSENCRYPT_ENABLED: "false"
    volumes:
      - ~/gotosocial/data:/gotosocial/storage

networks:
  gotosocial:

Four details matter here. First, pin the version (:0.22.0) instead of :latest — latest is a moving tag, and you want upgrades to be a deliberate decision. Second, replace social.example.com with your real domain; everything — keys, federation, your handle — is generated from this one variable. Third, if you are not using the built-in Let's Encrypt support, put a reverse proxy in front of it and terminate TLS there; our Caddy beginner guide covers the simplest reverse-proxy path. Fourth, the ~/gotosocial/data volume is the whole instance: it holds sqlite.db plus cached media, which is what you back up in step 8.

Run docker compose up -d and confirm the container is up with docker ps. The current release is v0.22.0, verified at write time against the official releases page.

Step 3: Create Your First Admin Account

GoToSocial has no setup wizard and no default credentials — the first account is created from the command line, and it must be promoted to admin before it can open the settings panel. Run these two commands against your running container:

docker exec -it gotosocial /gotosocial/gotosocial admin account create \
  --username you --email [email protected] --password 'a-strong-password'
docker exec -it gotosocial /gotosocial/gotosocial admin account promote \
  --username you

Now the gotcha nobody remembers: promotion is cached, so restart the container (docker restart gotosocial) before trying to log in as admin. Without the restart your shiny new admin will find the settings panel closed to them, and nothing in the logs will explain why.

Step 4: The Client Lesson — GoToSocial Ships With No Web App

This is the single biggest mental-model adjustment for newcomers: GoToSocial is a bare server. There is no Mastodon-style timeline in the browser waiting for you after login. The project says it plainly — it is "designed to be used thru external applications," and because it implements the Mastodon API, anything that supports the Mastodon API works with it.

The officially best-supported clients are Pinafore in the browser, Tusky on Android, and Feditext on iOS, iPadOS, and macOS. Pick one, point it at your domain, log in with the admin account, and you are in. Two things the server does serve directly: public profile pages and post permalinks (so links to your posts render on the open web), and the admin settings panel at https://your-domain/settings, where everything below lives.

Step 5: The Federation Rule — Follow Your First Remote Account

Following someone on another server is a lookup, not a browse: paste their handle (@[email protected]) or the full URL of their profile into your client's search bar. Your server performs a WebFinger lookup, pulls their profile, and the follow button appears. That handle-search habit is how you find everything remote — including old posts, which leads to the gotcha.

The no-backfill rule, said once: GoToSocial cannot fetch a remote account's older posts. You only see new posts published after you follow them. If you want to interact with an older post, copy its link from the account's web profile and paste it into your client's search bar — that pulls the single post in. Expect a quiet home timeline for the first days and do not mistake it for a broken install.

One more default to know: new posts are Unlisted, not Public. They reach your followers, but they do not appear on your profile page for strangers or get boosted onto other servers' federated timelines. Mark posts Public explicitly when you want them discoverable. On the moderation side, the default federation mode is a blocklist — open federation with everyone, block instances from the settings panel when they misbehave — while an experimental allowlist mode federates only with instances you explicitly approve.

Step 6: Media Caching — What Disappears and What Doesn't

Media has two lives in GoToSocial. Your own uploads are kept permanently and are never pruned. Remote media — images and videos attached to posts from other servers — is cached temporarily and cleaned on a schedule: the default media-remote-cache-duration is 7 days, swept by a nightly cleanup cron at midnight. So a meme from last month on a remote server will 404 its image while the post text survives.

Two version notes, current as of v0.22.0: the older GTS_MEDIA_REMOTE_CACHE_DAYS environment variable name has been replaced by the duration-based media-remote-cache-duration — use the new name in any config you write. And v0.22.0 added optional auto-cleanup of old remote statuses themselves (statuses-cleanup-remote-older-than), which defaults to off. None of this affects your posts; it only bounds how much of the rest of the Fediverse your disk remembers.

Step 7: Back It Up — the Database Is Your Identity

The official docs put it in the strongest terms they have: the GoToSocial database contains the instance as well as all user signing keys, and it is vital to back it up. Lose those keys and you can never federate from your domain again — there is no key-recovery flow, by design. Your backup is two things: sqlite.db (the entire instance: accounts, keys, posts, follows) and the media volume (your own attachments). Remote cached media can be skipped — it re-downloads.

# stop the container briefly for a clean copy
docker stop gotosocial
cp ~/gotosocial/data/sqlite.db ~/backups/gotosocial-$(date +%F).db
cp -r ~/gotosocial/data/storage/media ~/backups/gotosocial-media-$(date +%F)
docker start gotosocial

Encrypt the backups — they contain your private keys — and store a copy off the server. A daily cron of this shape is the difference between a hobby instance and a durable one.

Beginner Mistakes That Break a GoToSocial Instance

Almost every broken first install traces back to one of these. Check the table before you open the settings panel.

Sources

Every fact in this guide was verified against a page fetched on November 1, 2026: the GoToSocial documentation (installation, Docker container page, user creation, FAQ, federation modes, media caching, backup and restore), the official docker-compose example on Codeberg, the v0.22.0 release notes, and the project self-description on gotosocial.org.

Frequently Asked Questions

Is GoToSocial the same as Mastodon?

No. GoToSocial is a separate, lightweight ActivityPub server designed for small or single-user instances on low-powered hardware. It speaks the same ActivityPub and Mastodon-API protocols as Mastodon, so you can follow and be followed by anyone in the Fediverse, but it has no built-in web client, no official mobile app, no clustering, and is still pre-1.0 beta. Think of it as the single-user Mastodon alternative, not a Mastodon replacement.

Can I use GoToSocial in a web browser?

Yes, but through a client app, not a built-in interface. Pinafore is the officially best-supported browser client — point it at your domain and log in. The server itself serves profile pages, post permalinks, and the admin settings panel directly; everything else happens in your chosen client.

Can I change my instance's domain later?

Effectively no. Your domain is baked into your signing keys and your federated identity, and the official documentation warns that losing those keys means the domain can never federate again. Choose a domain you plan to keep for years before you deploy.

Why don't I see old posts from accounts I follow?

GoToSocial does not backfill remote history — it only receives posts published after you followed the account. To see or interact with an older post, copy its link from the account's web profile and paste it into your client's search bar, which pulls that single post in.

Is GoToSocial ready for everyday use?

It is stable enough for personal and small-group instances — many people run it as their daily social home — but it is still pre-1.0 beta, and the FAQ says that openly. Expect occasional sharp edges, follow the releases, and keep encrypted backups of your database.