📕 yarn is a Self-Hosted, Twitter™-like Decentralised micro-Blogging platform. No ads, no tracking, your content, your data! https://yarn.social/
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Go to file
James Mills 7dd5a93ed1
continuous-integration/drone/push Build is passing Details
Trigger CI
2 months ago
.chglog Fix CHANGELOG template (too noisey) 2 years ago
.dockerfiles Fix Docker entrypoint script 5 months ago
.sandstorm Sandstorm: launcher, file list (#1078) 7 months ago
.vscode Add feedtype icons next to the nick of each twt (#1036) 7 months ago
assets Add initial support for Sandstorm (packaging) 7 months ago
cmd Add support for shadow banning twts 4 months ago
contrib Upload iOS shortcut to post text/image to a Yarn.social instance (#851) 1 year ago
data Add support basic for ActivityPub (#1139) 4 months ago
deployment Oops, had left "Buccipod" in one of the options; fixed that 4 months ago
docs Provide extension list in overview and add make target (#1102) 6 months ago
internal Code cleanup 2 months ago
tools Update network-stats 4 months ago
.dockerignore Rename the binaries to yarn and yarnd 2 years ago
.drone.yml Fix Drone CI config 7 months ago
.gitignore Fix #1150 (The media-filter should also include the new class e-content for embedde video and audio) (#1151) 3 months ago
.goreleaser.yml Fix GoReleaser config 2 years ago
AUTHORS Add Deployment Guide Documentation (#933) 1 year ago
CHANGELOG.md feat-use-new-passwd (#1095) 6 months ago
CODE_OF_CONDUCT.md Add Contributor Code of Conduct 3 years ago
CONTRIBUTING.md Update contributing guidelines 2 years ago
Dockerfile Add support basic for ActivityPub (#1139) 4 months ago
Dockerfile.dev Fix the Dockerfile.dev used by docker-compose.yml 1 year ago
LICENSE Update LICENSE to AGPLv3 and update README (#794) 1 year ago
Makefile Doc updates (#1148) 3 months ago
README.md Doc updates (#1148) 3 months ago
README_ZH.md README*: Use absolute paths for alternate language links (#1077) 7 months ago
attachment.json Fix panic bug in TwtFromNote() where parent note was shadowing note 2 months ago
doc.go Add extra build info (#1115) 5 months ago
docker-compose.yml Add Health Check to Docker Container (#958) 1 year ago
docker-stack.yml Add Health Check to Docker Container (#958) 1 year ago
go.mod Add basic support for cleaning up Activity Pub notes, rewriting mentions and converting HTML to Markdown 2 months ago
go.sum Add basic support for cleaning up Activity Pub notes, rewriting mentions and converting HTML to Markdown 2 months ago
preflight.sh Update Sandstorm base box 7 months ago
version.go Add extra build info (#1115) 5 months ago


Yarn social

Yarn - a decentralised self-hosted social media that has a privacy-first focus.

View the chinese version of this document


Pre-built Binaries

As a first point, please try to use one of the pre-built binaries that are available on the Releases page.

Using Homebrew

We provide Homebrew formulae for macOS users for both the command-line client (yarnc) as well as the server (yarnd).

brew tap yarnsocial/yarn https://git.mills.io/yarnsocial/homebrew-yarn.git
brew install yarn

Run the server:


Run the command-line client:


Building from source

This is an option if you are familiar with Go development.

  1. Clone this repository (this is important)
git clone https://git.mills.io/yarnsocial/yarn.git
  1. Install required dependencies (this is important)

Linux, macOS:

make deps

Note that in order to get the media upload functions to work, you need to install ffmpeg and its associated -dev packages. Consult your distribution's package repository for availability and names.


  • Install gmake
  • Install pkgconf that brings pkg-config
gmake deps
  1. Build the binaries

Linux, macOS:

  • The server
make server
  • The client
make cli
  • List all options
make help




Command-line Client

  1. Login to your Yarn.social pod:
$ ./yarnc login
INFO[0000] Using config file: /Users/prologic/.twt.yaml
  1. Viewing your timeline
$ ./yarnc timeline
INFO[0000] Using config file: /Users/prologic/.twt.yaml
> prologic (50 minutes ago)
Hey @rosaelefanten 👋 Nice to see you have a Twtxt feed! Saw your [Tweet](https://twitter.com/koehr_in/status/1326914925348982784?s=20) (_or at least I assume it was yours?_). Never heard of `aria2c` till now! 🤣 TIL

> dilbert (2 hours ago)
Angry Techn Writers ‣ https://dilbert.com/strip/2020-11-14
  1. Making a Twt (post):
$ ./yarnc post
INFO[0000] Using config file: /Users/prologic/.twt.yaml
Testing `yarn` the command-line client
INFO[0015] posting twt...
INFO[0016] post successful

For additional help on using the yarnc command-line client:

$ yarnc help
This is the command-line client for Yarn.social pods running
yarnd. This tool allows a user to interact with a pod to view their timeline,
following feeds, make posts and managing their account.

  yarnc [command]

Available Commands:
  completion  generate the autocompletion script for the specified shell
  help        Help about any command
  login       Login and authenticate to a Yarn.social pod
  post        Post a new twt to a Yarn.social pod
  stats       Parses and performs statistical analytis on a Twtxt feed given a URL or local file
  timeline    Display your timeline

  -c, --config string   set a custom config file (default "/Users/prologic/.yarnc.yml")
  -D, --debug           Enable debug logging
  -h, --help            help for yarnc
  -t, --token string    yarnd API token to use to authenticate to endpoints (default "$YARNC_TOKEN")
  -U, --uri string      yarnd API endpoint URI to connect to (default "http://localhost:8000/api/v1/")

Use "yarnc [command] --help" for more information about a command.

Deploy With Docker Swarm and Cloudflare

Visit: deployment

Deploy with Docker Compose

Run the compose configuration:

docker-compose up -d

Then visit: http://localhost:8000/

Web App

Run yarnd:

yarnd -R

NOTE: Registrations are disabled by default so hence the -R flag above.

Then visit: http://localhost:8000/

You can configure other options by specifying them on the command-line or via environment variables.

To view the available options simply run:

$ ./yarnd --help

Valid environment value names are the long-option version of a flag in all uppercase with dashes repalced by an underscore _.

Configuring your Pod

At a bare minimum you should set the following options:

  • -d /path/to/data
  • -s bitcask:///path/to/data/twtxt.db (we will likely simplify/default this)
  • -n <name> to give your pod a unique name.
  • -u <url> the base url (public facing) of how your pod will be reahced on the web.
  • -R to enable open registrations.
  • -O to enable open profiles.

Most other configuration values should be done via environment variables.

It is recommended you pick an account you want to use to "administer" the pod with and set the following environment values:

  • ADMIN_USER=username
  • ADMIN_EMAIL=email

In order to configure email settings for password recovery and the /support and /abuse endpoints, you should set appropriate SMTP_ values.

It is highly recommended you also set the following values to secure your Pod:


These values should be generated with a secure random number generator and be of length 64 characters long. You can use the following shell snippet to generate secrets for your pod for the above values:

$ cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 64 | head -n 1

There is a shell script in ./tools/gen-secrets.sh you can use to conveniently generate the required secrets for a production pod. The output is designed to by copy/pasted into a docker-compose.yml file with the right indentation.

DO NOT publish or share these values. BE SURE to only set them as env vars.

NOTE: The Dockerfile specifies that the container run as the user yarnd with uid=1000. Be sure that any volume(s) you mount into your container and use as the data storage (-d/--data) path and database storage path (-s/--store) is correctly configured to have the correct user/group ownership. e.g: chorn -R 1000:1000 /data

Production Deployments

Docker Swarm

You can deploy yarnd to a Docker Swarm cluster by utilising the provided yarn.yaml Docker Stack. This also depends on and uses the Traefik ingress load balancer so you must also have that configured and running in your cluster appropriately.

docker stack deploy -c yarn.yml


Interested in contributing to this project? You are welcome! Here are some ways you can contribute:

  • File an Issue -- For a bug, or interesting idea you have for a new feature or just general questions.
  • Submit a Pull-Request or two! We welcome all PR(s) that improve the project!

Please see the Contributing Guidelines and checkout the Developer Documentation or over at /docs.


Thank you to all those that have contributed to this project, battle-tested it, used it in their own projects or products, fixed bugs, improved performance and even fix tiny typos in documentation! Thank you and keep contributing!

You can find an AUTHORS file where we keep a list of contributors to the project. If you contribute a PR please consider adding your name there.


yarn is licensed under the terms of the AGPLv3 License