How to do it
- Get the code Clone the repository from https://github.com/socialhandoff/socialhandoff.
- Pick a path For a single machine, run docker compose --profile aio up --build aio. For separate services, use the default Compose file.
- Set an encryption key For Compose, set SOCIALHANDOFF_ENCRYPTION_KEY to 32 random bytes, for example with openssl rand -hex 32, and keep it in .env. The all-in-one image generates and stores one for you.
- Start and claim the server The first start prints a one-time setup URL in the log. Open it, create the workspace, and save the owner key.
- Connect networks Bluesky and Mastodon work straight away. For X and LinkedIn, create your own apps and set their client IDs and secrets.
- Put it behind TLS Ports bind to 127.0.0.1 by default. Put a TLS reverse proxy in front before you expose it.
- Back up Dump Postgres with pg_dump and keep the encryption key with the dump.
What runs
Compose starts Postgres 16, Redis 7, MinIO for media, the API on port 43110, the worker, and the web inbox on port 43111. The all-in-one image runs the same services in one container, with data under a single volume.
To try it without real accounts, DEMO=true docker compose up --build seeds a demo workspace with a mock network. Never put real tokens in a demo instance; its keys are public.
Without Docker
With Node 22+, pnpm, Postgres, and Redis installed, ./run.sh installs, migrates, and starts everything. ./run.sh --real skips the demo data and prints a setup URL.
Key settings
| Variable | Why it matters |
|---|---|
| SOCIALHANDOFF_ENCRYPTION_KEY | Encrypts tokens. Required outside demo mode |
| SOCIALHANDOFF_PUBLIC_URL | Public API origin, used for OAuth callbacks |
| SOCIALHANDOFF_WEB_URL | Browser origin for the inbox |
| SOCIALHANDOFF_DEMO | 0 for real use |
Backups and upgrades
A database dump without the encryption key cannot decrypt tokens, so store them together. To upgrade: back up, pull the new version, keep the same key, and start the API; migrations apply on boot. Downgrades need a restore.
Kubernetes, Railway, Render
The repository has a starting Helm chart and Railway and Render configs. See open source and the self-hosting glossary entry.