yarn

README

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

View the chinese version of this document

Table of Contents:

• Quick Start
• Installation
  • Pre-built Binaries
  • Using Homebrew
  • Building from source
• Clients
  • Command-line Client
  • Other clients
• Deployment
  • Deploy With Docker
  • Deploy with Docker Swarm
  • Other deployments
• Configuration
• Contributing
• Contributors
• Related Projects
• License

Quick Start

The quickest and easiest way to try our Yarn.social is to try the demo:

https://demo.yarn.social/

[!WARNING]
This demo instance is deliberately kept locked down to prevent abuse. Some functionality will be restricted as a result.

Alternatively you can try things out locally by running:

docker run -p 8000:8000 prologic/yarnd

And visit http://localhost:8000 in your browser.

See the Deployment section for other detailed deployment options.

Installation

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:

yarnd

Run the command-line client:

yarnc

Building from source

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

[!IMPORTANT] Be sure to have $GOBIN (if not empty) or your $GOPATH/bin in your $PATH. See Compile and install packages and dependencies

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] In order to get the media upload functions to work, you need to install ffmpeg and its associated -dev packages. Consult your OS software or package manager availability and how to install these dependencies.

FreeBSD:

• 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

FreeBSD:

gmake

Clients

Command-line Client

Every Yarn.social pod provides an API that can be used alongside the builtin web interface. There is also a command-lint client that uses the API. Here's a basic guide on using the command-line client:

1. Login to your Yarn.social pod:

$ ./yarnc login
INFO[0000] Using config file: /Users/prologic/.twt.yaml
Username:

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.

Usage:
  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

Flags:
  -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.

Other clients

• go.yarn.social/client The officially maintained client library for accessing the yarnd API. This is used by the command-line client above.
• twt.js An old unmaintained Javascript client. If you are interested in maintaining this client, please contact us. See Contributing

Deployment

Deploy With Docker

If you are comfortable using Docker you can easily deploy a Yarn.social pod by using the provided Docker image prologic/yarnd which are regularly published for both AMD64 and ARM64 platforms.

Running or testing yarnd locally is as easy as running:

$ docker run -p 8000:8000 prologic/yarnd

And visiting http://localhost:8000 in your browser.

Alternatively you can also use Docker Compose to manage your deployment. A sample docker-compose.yaml is provided in the root directory of the source code. You can run it locally by running:

docker-compose up -d

[!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

Deploy with 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

See deployment for a full guide on a production deployment.

Other deployments

To deploy a pod running yarnd on your system, install the yarnd binary in an appropriate location such as /usr/local/bin. Next ensure you have a path for storing your pod's data. This path will contain the database, feeds, avatars, cache, index, archive and a few other files.

[!IMPORTANT]
It is important that you backup your /path/to/data directory used for your pod regularly. Using tools like tar and scp is enough to copy and backup the files.

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 replaced by an underscore _.

Configuration

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 reached 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.

A production pod (that is one run without the -D/--debug flag) MUST be configured with the following additional options:

• API_SIGNING_KEY
• COOKIE_SECRET
• MAGICLINK_SECRET

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.

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

Contributing

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.

Contributors

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.

Related Projects

• Yarn.social -- Yarn.social landing page
• Search -- The Yarn.social search engine hosted at search.twtxt.net
• App -- Our Flutter iOS and Android Mobile App
• Feeds -- RSS/Atom/Twitter to Twtxt aggregator service hosted at feeds.twtxt.net

License

yarn is licensed under the terms of the AGPLv3 License

Documentation

Overview

Package yarn is a Self-Hosted, Twitter™-like Decentralised microBlogging platform.

Copyright (C) 2020-present Yarn.social

yarn is covered by the AGPLv3 license:

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Index

• Variables
• func FullVersion() string

Variables

var (
	// Version is the tagged release version in the form <major>.<minor>.<patch>
	// following semantic versioning and is overwritten by the build system.
	Version = defaultVersion

	// Commit is the commit sha of the build (normally from Git) and is overwritten
	// by the build system.
	Commit = defaultCommit

	// Build is the date and time of the build as an RFC3339 formatted string
	// and is overwritten by the build system.
	Build = defaultBuild
)

Functions

func FullVersion

func FullVersion() string

FullVersion display the full version and build