Deploying GoToSocial with Traefik and Phanpy

| A small social server in a very cozy pixel world. |
Table of Contents ๐
- Changelog
- 1. Prerequisites
- 2. GoToSocial Directory
- 3. GoToSocial Docker Compose
- 4. Create the First Account
- 5. Phanpy Web Client
- 6. Verification
- 7. Search, Discovery, and Trending
- 8. Backups and Updates
- 9. Optional: Migrating from Mastodon
- 10. Optional: Legacy Mastodon Proxy
- Conclusion
- Verify the embedded runtime during updates
- Sources
GoToSocial is a lightweight ActivityPub server for small Fediverse instances. It is especially attractive for single-user or small-group deployments where a full Mastodon stack would be unnecessarily heavy.
This guide focuses on a fresh GoToSocial installation in an existing Traefik v3 and CrowdSec Docker ecosystem. GoToSocial runs as a normal Docker Compose stack on the shared proxy network, Traefik handles public HTTPS, and Phanpy is deployed as a separate static web client.
| โน๏ธ FRESH INSTALL FIRST |
The main path below is a clean installation. If you are replacing an existing Mastodon account, use the optional migration section near the end after GoToSocial itself is already working. |
Changelog
| Date | Change |
|---|---|
| 2026-10-27 | Added the remote-account identity fix, patched Go build requirement and maintained proxy image. |
| 2026-10-22 | Added image-bound Go runtime and rollback verification. |
| 2026-10-11 | Fixed middleware routing, documented the 0.22.2 two-factor authentication fix, and added login/OAuth/2FA and isolated restore checks. |
| 2026-09-04 | Maintenance Update: Updated the pinned GoToSocial image to 0.22.1 and added a safer SQLite-first update procedure with explicit version and HTTP checks. |
| 2026-07-01 | Initial Version: Fresh GoToSocial install with SQLite, Traefik, Phanpy, and optional Mastodon account-move notes. |
1. Prerequisites
You need:
- A working Traefik v3 and CrowdSec stack.
- A subdomain for GoToSocial, e.g.
gotosocial.your-domain.com. - A subdomain for Phanpy, e.g.
phanpy.your-domain.com. - DNS
A/AAAArecords pointing both subdomains at your server. - Docker and Docker Compose.
This guide assumes the Traefik external Docker network is named proxy.
2. GoToSocial Directory
sudo mkdir -p /opt/containers/gotosocial
cd /opt/containers/gotosocial
sudo mkdir -p data cache
sudo chown -R 1000:1000 data cacheThe example below runs the container as UID/GID 1000:1000. If your deployment uses another unprivileged user, adjust ownership and user: accordingly.
3. GoToSocial Docker Compose
Create /opt/containers/gotosocial/docker-compose.yml:
services:
gotosocial:
image: docker.io/superseriousbusiness/gotosocial:0.22.3
container_name: gotosocial
user: 1000:1000
restart: unless-stopped
environment:
GTS_HOST: gotosocial.your-domain.com
GTS_DB_TYPE: sqlite
GTS_DB_ADDRESS: /gotosocial/storage/sqlite.db
GTS_LETSENCRYPT_ENABLED: "false"
GTS_TRUSTED_PROXIES: 172.18.0.0/16
GTS_WAZERO_COMPILATION_CACHE: /gotosocial/.cache
GTS_MEDIA_REMOTE_CACHE_DURATION: "14 days"
GTS_STATUSES_CLEANUP_REMOTE_OLDER_THAN: "30 days"
GIN_MODE: release
TZ: Europe/Berlin
volumes:
- ./data:/gotosocial/storage
- ./cache:/gotosocial/.cache
networks:
- proxy
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.gotosocial.rule=Host(`gotosocial.your-domain.com`)"
- "traefik.http.routers.gotosocial.entrypoints=websecure"
- "traefik.http.routers.gotosocial.tls.certresolver=tls_resolver"
- "traefik.http.routers.gotosocial.middlewares=security-headers@file,crowdsec-bouncer@file"
- "traefik.http.services.gotosocial.loadbalancer.server.port=8080"
networks:
proxy:
external: trueConfiguration notes:
GTS_LETSENCRYPT_ENABLED=false: Traefik handles public TLS.GTS_TRUSTED_PROXIES: restrict this to your Docker proxy subnet.GTS_MEDIA_REMOTE_CACHE_DURATION: limits cached remote media growth.GTS_STATUSES_CLEANUP_REMOTE_OLDER_THAN: cleans old remote statuses.- SQLite is appropriate for a small personal instance.
Start the service:
sudo docker compose pull
sudo docker compose up -d
sudo docker compose logs -f gotosocial4. Create the First Account
Create the account from inside the container:
sudo docker exec -it gotosocial \
/gotosocial/gotosocial admin account create \
--username yourusername \
--email you@your-domain.com \
--password 'REPLACE_WITH_A_STRONG_TEMPORARY_PASSWORD'Promote it to admin:
sudo docker exec -it gotosocial \
/gotosocial/gotosocial admin account promote \
--username yourusernameLog in at:
https://gotosocial.your-domain.com/settingsChange the temporary password immediately.
5. Phanpy Web Client
GoToSocial provides settings pages and API endpoints, but you usually want a full client for daily use. Phanpy works well as a static web client.
Create the directory:
sudo mkdir -p /opt/containers/phanpy/html
cd /opt/containers/phanpyDownload and verify the Phanpy release asset you want to run, then extract it into html/.
| ๐ก VERIFY RELEASE ASSETS |
When using prebuilt static client assets, verify the checksum from the release page before serving them publicly. |
Create /opt/containers/phanpy/nginx.conf:
worker_processes 2;
user www-data;
events {
use epoll;
worker_connections 128;
}
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
sendfile on;
tcp_nopush on;
tcp_nodelay on;
keepalive_timeout 65;
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
location ~* \.(?:css|js|mjs|png|jpg|jpeg|gif|svg|webp|avif|ico|woff2?)$ {
try_files $uri =404;
access_log off;
expires 30d;
add_header Cache-Control "public, immutable";
}
location / {
try_files $uri $uri/ /index.html;
add_header Cache-Control "no-cache";
}
}
}Create /opt/containers/phanpy/docker-compose.yml:
services:
phanpy:
image: nginx:1.30.6
container_name: phanpy
restart: unless-stopped
volumes:
- ./html:/usr/share/nginx/html:ro
- ./nginx.conf:/etc/nginx/nginx.conf:ro
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.phanpy.rule=Host(`phanpy.your-domain.com`)"
- "traefik.http.routers.phanpy.entrypoints=websecure"
- "traefik.http.routers.phanpy.tls.certresolver=tls_resolver"
- "traefik.http.routers.phanpy.middlewares=security-headers@file,crowdsec-bouncer@file"
- "traefik.http.services.phanpy.loadbalancer.server.port=80"
networks:
- proxy
networks:
proxy:
external: trueStart it:
sudo docker compose up -dOpen:
https://phanpy.your-domain.com/Choose your GoToSocial instance as the server when logging in.
6. Verification
Check the public profile:
curl -I https://gotosocial.your-domain.com/@yourusernameCheck WebFinger:
curl -s 'https://gotosocial.your-domain.com/.well-known/webfinger?resource=acct:yourusername@gotosocial.your-domain.com'Check logs:
cd /opt/containers/gotosocial
sudo docker compose logs -f gotosocialVerify the Phanpy route:
curl -I https://phanpy.your-domain.com/At this point, the fresh GoToSocial installation is ready. You can use Phanpy or any compatible Mastodon/ActivityPub client to log in.
7. Search, Discovery, and Trending
A fresh GoToSocial instance only knows local accounts and remote objects it has already discovered. Global search is not a search engine over the entire Fediverse.
To discover more content:
- Follow accounts from known instances.
- Open remote profile URLs directly in your client.
- Follow hashtags.
- Interact with posts so your instance learns about those actors and threads.
It is normal for trending posts or broad search results to look empty at first.
8. Backups and Updates
GoToSocial 0.22.2 fixes a two-factor authentication bypass: someone who already knows an accountโs email address and password could obtain an OAuth token without the second factor. Instances using 0.22.0 or 0.22.1 should apply this fix even if the service appears healthy. The official 0.22.2 release notes distinguish the simple update within 0.22.x from the database migrations required when upgrading older releases.
GoToSocial 0.22.3 additionally fixes remote-account impersonation through crafted URLs in the dereferencer. It also raises the required Go build version to 1.26.10 to mitigate CVE-2026-111943 in certificate validation. A same-source rebuild of 0.22.2 with a patched Go compiler addresses the runtime issue, but does not include the separate application-level identity fix. The official 0.22.3 release notes report no new database migrations within 0.22.x. Verify the actual image and executable rather than assuming a tag proves the compiler version. The Phanpy example also uses a maintained nginx stable image; check nginx security advisories before replacing an older proxy image.
Back up:
/opt/containers/gotosocial/data
/opt/containers/gotosocial/docker-compose.yml
/opt/containers/phanpy/html
/opt/containers/phanpy/docker-compose.yml
/opt/containers/phanpy/nginx.confRead the release notes before every update. For SQLite deployments, stop the service before copying the database so the backup is a consistent single file. Then change the pinned image tag, validate the Compose file, and recreate the service:
cd /opt/containers/gotosocial
# Download the target image before starting the maintenance window.
sudo docker pull docker.io/superseriousbusiness/gotosocial:0.22.3
sudo docker compose stop gotosocial
sudo cp -a data/sqlite.db "data/sqlite-pre-update-$(date +%F).db"
sudo cp -a docker-compose.yml "docker-compose.yml.pre-update-$(date +%F)"
# Edit docker-compose.yml and pin the reviewed release, for example 0.22.3.
sudo docker compose config -q
sudo docker compose up -d --remove-orphans
# Confirm startup, the exact running version, and the public routes.
sudo docker compose logs --tail=100 gotosocial
sudo docker exec gotosocial /gotosocial/gotosocial --version
curl -fsS https://gotosocial.your-domain.com/api/v1/instance
curl -I https://gotosocial.your-domain.com/settingsDo not interrupt startup while GoToSocial reports database migrations. The update from an earlier 0.22.x release to 0.22.3 has no new database migration, but this is release-specific and must not be assumed for later versions.
Validate authentication as well as HTTP availability after an update. A password login should complete the clientโs OAuth authorization and allow an authenticated account request. For an account using two-factor authentication, verify that the password leads to the second-factor challenge, an invalid code is rejected, and a valid code completes OAuth. The 0.22.2 regression check is that directly posting to /oauth/authorize after the password step cannot issue an authorization code while the second factor is still pending. Use a synthetic account in an isolated test copy for this check; do not expose passwords, TOTP seeds, recovery codes, or OAuth tokens in test output.
Prove that the backup can be restored before treating the update as complete. Restore the consistent SQLite backup to a separate writable directory, compare its SHA-256 with the saved backup, run SQLite PRAGMA integrity_check, and boot the reviewed GoToSocial image against that copy. An internal Docker network with no published ports keeps the restored instance away from SMTP, federation, OIDC, and webhook destinations. Keep the production hostname and account-domain values in the restored configuration, but do not attach the test instance to the public proxy. Explicitly set --entrypoint /gotosocial/gotosocial when using docker run for native admin commands because the image entrypoint already includes server start. Remove the test instance and copied database after verification. This proves database recovery; verify media and configuration restoration separately when testing recovery of the complete instance.
/api/v1/instance is a suitable availability and version probe. GoToSocial 0.22.2 does not provide a /health endpoint; a 404 there does not establish an outage. An HTTP probe also needs a regular User-Agent so that the serverโs bot filter does not reject the request before it reaches the application endpoint.
For Phanpy, replace the static release files in html/ with a verified newer release and recreate the Nginx container if needed.
9. Optional: Migrating from Mastodon
GoToSocial is not a drop-in Mastodon database replacement. If you are replacing an existing Mastodon account, treat it as an ActivityPub identity move after the new GoToSocial instance has been installed and tested.
The migration flow is:
- Keep the old Mastodon account reachable.
- Create the new GoToSocial account.
- Add an alias in GoToSocial pointing to the old Mastodon account.
- Trigger the account move from the old Mastodon account to the new GoToSocial account.
- Import or recreate follows.
- Recreate hashtag follows separately if needed.
| โ ๏ธ KEEP THE OLD ACCOUNT REACHABLE |
ActivityPub account moves depend on the old account being reachable long enough for other servers to observe the move. Do not shut down the old Mastodon hostname immediately after changing DNS. |
9.1. Add the GoToSocial Alias
In GoToSocial settings:
https://gotosocial.your-domain.com/settings/user/migrationAdd the old Mastodon account as an alias, for example:
https://mastodon.your-domain.com/@yourusernameor:
https://mastodon.your-domain.com/users/yourusername9.2. Trigger the Move in Mastodon
Log in to the old Mastodon account and move it to:
@yourusername@gotosocial.your-domain.comMastodon will mark the old profile as moved and notify followersโ servers. Propagation is not instant.
9.3. Following and Hashtags
Follower migration is handled by the ActivityPub move. Following relationships are different: export your Mastodon following list and import it into GoToSocial if the UI supports it, or recreate the follows through a client/API workflow.
Hashtag follows are not guaranteed to migrate with account moves or account CSV imports. Export and recreate them separately.
After the account move, search for the old Mastodon account from another Fediverse instance and verify that it points to the new GoToSocial account.
10. Optional: Legacy Mastodon Proxy
During a migration, it can be useful to keep mastodon.your-domain.com reachable even after the new server handles DNS. A temporary Traefik file-provider route can proxy the old Mastodon host back to the old server.
Remove this after the fallback window has ended. Keeping a legacy proxy forever makes the migration harder to reason about.
Conclusion
GoToSocial fits neatly into a Traefik-based Docker setup: one small application container, SQLite storage for small instances, no public host port, and a separate static web client through the same reverse proxy. If you later replace Mastodon, handle that as an ActivityPub account move, not as a database transplant.
๐ ๐ฆ ๐Verify the embedded runtime during updates
Record the GoToSocial application release and the Go build information of its actual executable. An up-to-date application tag does not establish that its embedded runtime is supported or patched. Compare it with the Go release policy and security revisions; a host compiler update leaves existing container executables unchanged. Prefer a compatible maintained image, preserve configuration/data and the prior image, then verify authenticated reads, media and federation after replacement. Go executable build metadata, Docker image update guidance.





