📕 yarn is a Self-Hosted, Twitter™-like Decentralised micro-Blogging platform. No ads, no tracking, your content, your data! https://yarn.social/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
James Mills 5863328c80
Update CHANGELOG for 0.7.4
9 months ago
.chglog Move source code and rename Go module to git.mills.io/yarnsocial/yarn 1 year ago
.dockerfiles Fix Docker image to just work without any arguments and drop chown of default data volume 9 months ago
client Fix consistency of Pod URL for the yarnc command-line client to match the mobile app just taking a Pod URL 9 months ago
cmd Fix and improve the yarnc timeline to support Markdown rendering and fix multi-line twts 9 months ago
contrib Updated Grafana Dashboard 2 years ago
data Add support for custom pages (Fixes #393) 9 months ago
docs Add pagination extension spec (#494) 9 months ago
internal Put the responsibility on the caller to take a copy of the GetByUserView slice 9 months ago
tests Remove accidently committed tests inary 10 months ago
tools Update tools/check-versions.sh with new pod: txt.quisquiliae.com 9 months ago
types Add experimental StripConvSubjectHashes (strip_conv_subject_hashes) feature 9 months ago
.dockerignore Rename the binaries to yarn and yarnd 1 year ago
.drone.yml Remove some expensive CI (for now) 9 months ago
.gitignore Fix the name of the default database, app specific JS and CSS files 10 months ago
.goreleaser.yml Fix GoReleaser config 10 months ago
AUTHORS remove Prev / Next buttons if no further pages (#458) 10 months ago
CHANGELOG.md Update CHANGELOG for 0.7.4 9 months ago
CODE_OF_CONDUCT.md Add Contributor Code of Conduct 2 years ago
CONTRIBUTING.md Update contributing guidelines 9 months ago
Dockerfile Fix signal handling using su-exec and ownership of default data volume /data 9 months ago
Dockerfile.dev Add first-class support for themes to more easily customize templates and static assets 10 months ago
LICENSE Remove all referenced to we-ware-twtxt format 10 months ago
Makefile Fix the name of the default database, app specific JS and CSS files 10 months ago
README.md Removed warning regarding #250 (#516) 9 months ago
README_ZH.md Remove all referenced to we-ware-twtxt format 10 months ago
doc.go More fixes 1 year ago
docker-compose.yml Fix docker-compose 1 year ago
docker-stack.yml Fix example Docker Compose for Docker Swarm to match Docker image entrypoint chagne 9 months ago
go.mod Update deps 9 months ago
go.sum Update deps 9 months ago
preflight.sh Fix preflight check for Go1.17 10 months ago
version.go More fixes 1 year ago



Build Status

📕 yarn is a Self-Hosted, Twitter™-like Decentralised micro-Blogging platform. No ads, no tracking, your content, your data!

  • yarnd is the Yarn.social pod backend server
  • yarnc is the command-line client to yarnd API and command-line Twtxt client

See [Yarn.social] for more deatils


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 (yarn) 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:





Command-line Client

  1. Login to your Yarn.social pod:
$ ./yarn login
INFO[0000] Using config file: /Users/prologic/.twt.yaml
  1. Viewing your timeline
$ ./yarn 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):
$ ./yarn 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 euthenticate 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 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:

$ ./yarnd --help
Usage of ./yarnd:
  -E, --admin-email string            default admin user email (default "support@yarn.social")
  -N, --admin-name string             default admin user name (default "Administrator")
  -A, --admin-user string             default admin user to use (default "admin")
      --api-session-time duration     timeout for api tokens to expire (default 240h0m0s)
      --api-signing-key string        secret to use for signing api tokens (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
  -u, --base-url string               base url to use (default "")
  -b, --bind string                   [int]:<port> to bind to (default "")
      --cookie-secret string          cookie secret to use secure sessions (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
  -d, --data string                   data directory (default "./data")
  -D, --debug                         enable debug logging
  -m, --description string            set the pod's description (default "🧶 Yarn.social is a Self-Hosted, Twitter™-like Decentralised microBlogging platform. No ads, no tracking, your content, your data!")
      --enable-feature feature        enable the named feature
      --feed-sources strings          external feed sources for discovery of other feeds (default [https://feeds.twtxt.net/we-are-feeds.txt])
      --fetch-interval string         cache fetch interval (how often to update feeds) in cron syntax (https://pkg.go.dev/github.com/robfig/cron) (default "@every 5m")
  -l, --lang string                   set the default language (default "auto")
      --magiclink-secret string       magiclink secret to use for password reset tokens (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
  -I, --max-cache-items int           maximum cache items (per feed source) of cached twts in memory (default 150)
  -C, --max-cache-ttl duration        maximum cache ttl (time-to-live) of cached twts in memory (default 240h0m0s)
  -F, --max-fetch-limit int           maximum feed fetch limit in bytes (default 2097152)
  -L, --max-twt-length int            maximum length of posts (default 288)
  -U, --max-upload-size int           maximum upload size of media (default 16777216)
  -n, --name string                   set the pod's name (default "twtxt.net")
  -O, --open-profiles                 whether or not to have open user profiles
  -R, --open-registrations            whether or not to have open user registgration
  -P, --parser string                 set active parsing engine (default "lextwt")
      --pop3-bind string              POP3 interface and port to bind to (default "")
      --session-cache-ttl duration    time-to-live for cached sessions (default 1h0m0s)
      --session-expiry duration       timeout for sessions to expire (default 240h0m0s)
      --smtp-bind string              SMTP interface and port to bind to (default "")
      --smtp-from string              SMTP From to use for email sending (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
      --smtp-host string              SMTP Host to use for email sending (default "smtp.gmail.com")
      --smtp-pass string              SMTP Pass to use for email sending (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
      --smtp-port int                 SMTP Port to use for email sending (default 587)
      --smtp-user string              SMTP User to use for email sending (default "INVALID CONFIG VALUE - PLEASE CHANGE THIS VALUE")
  -s, --store string                  store to use (default "bitcask://twtxt.db")
  -t, --theme string                  set the default theme (default "auto")
      --transcoder-timeout duration   timeout for the video transcoder (default 10m0s)
  -T, --twts-per-page int             maximum twts per page to display (default 50)
  -v, --version                       display version information
      --whitelist-domain strings      whitelist of external domains to permit for display of inline images (default [imgur\.com,giphy\.com,imgs\.xkcd\.com,tube\.mills\.io,reactiongifs\.com,githubusercontent\.com])
pflag: help requested

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)
  • -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

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 MIT License