README.md 9.97 KB
Newer Older
1 2 3
Mastodon
========

Eugen's avatar
Eugen committed
4 5
[![Build Status](http://img.shields.io/travis/tootsuite/mastodon.svg)][travis]
[![Code Climate](https://img.shields.io/codeclimate/github/tootsuite/mastodon.svg)][code_climate]
6

Eugen's avatar
Eugen committed
7 8
[travis]: https://travis-ci.org/tootsuite/mastodon
[code_climate]: https://codeclimate.com/github/tootsuite/mastodon
Eugen Rochko's avatar
Eugen Rochko committed
9

10
Mastodon is a free, open-source social network server. A decentralized solution to commercial platforms, it avoids the risks of a single company monopolizing your communication. Anyone can run Mastodon and participate in the social network seamlessly.
Eugen's avatar
Eugen committed
11 12

An alternative implementation of the GNU social project. Based on ActivityStreams, Webfinger, PubsubHubbub and Salmon.
13

Eugen Rochko's avatar
Eugen Rochko committed
14 15
Click on the screenshot to watch a demo of the UI:

Eugen's avatar
Eugen committed
16
[![Screenshot](https://i.imgur.com/T2q5V65.png)][youtube_demo]
Eugen Rochko's avatar
Eugen Rochko committed
17 18

[youtube_demo]: https://www.youtube.com/watch?v=YO1jQ8_rAMU
Eugen's avatar
Eugen committed
19

rbaumert's avatar
rbaumert committed
20
The project focus is a clean REST API and a good user interface. Ruby on Rails is used for the back-end, while React.js and Redux are used for the dynamic front-end. A static front-end for public resources (profiles and statuses) is also provided.
Eugen's avatar
Eugen committed
21

22
If you would like, you can [support the development of this project on Patreon][patreon]. Alternatively, you can donate to this BTC address: `17j2g7vpgHhLuXhN4bueZFCvdxxieyRVWd`
Eugen's avatar
Eugen committed
23 24 25 26 27

[patreon]: https://www.patreon.com/user?u=619786

## Resources

28
- [List of Mastodon instances](https://github.com/tootsuite/documentation/blob/master/Using-Mastodon/List-of-Mastodon-instances.md)
Eugen's avatar
Eugen committed
29
- [Use this tool to find Twitter friends on Mastodon](https://mastodon-bridge.herokuapp.com)
30 31 32
- [API overview](https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md)
- [Frequently Asked Questions](https://github.com/tootsuite/documentation/blob/master/Using-Mastodon/FAQ.md)
- [List of apps](https://github.com/tootsuite/documentation/blob/master/Using-Mastodon/Apps.md)
33

Eugen Rochko's avatar
Eugen Rochko committed
34 35
## Features

Eugen Rochko's avatar
Eugen Rochko committed
36
- **Fully interoperable with GNU social and any OStatus platform**
Eugen Rochko's avatar
Eugen Rochko committed
37
  Whatever implements Atom feeds, ActivityStreams, Salmon, PubSubHubbub and Webfinger is part of the network
Eugen Rochko's avatar
Eugen Rochko committed
38
- **Real-time timeline updates**
Eugen Rochko's avatar
Eugen Rochko committed
39
  See the updates of people you're following appear in real-time in the UI via WebSockets
Eugen Rochko's avatar
Eugen Rochko committed
40
- **Federated thread resolving**
Eugen Rochko's avatar
Eugen Rochko committed
41
  If someone you follow replies to a user unknown to the server, the server fetches the full thread so you can view it without leaving the UI
Eugen Rochko's avatar
Eugen Rochko committed
42
- **Media attachments like images and WebM**
Eugen Rochko's avatar
Eugen Rochko committed
43
  Upload and view images and WebM videos attached to the updates
Eugen Rochko's avatar
Eugen Rochko committed
44
- **OAuth2 and a straightforward REST API**
Eugen Rochko's avatar
Eugen Rochko committed
45
  Mastodon acts as an OAuth2 provider so 3rd party apps can use the API, which is RESTful and simple
Eugen Rochko's avatar
Eugen Rochko committed
46
- **Background processing for long-running tasks**
Eugen Rochko's avatar
Eugen Rochko committed
47
  Mastodon tries to be as fast and responsive as possible, so all long-running tasks that can be delegated to background processing, are
Eugen Rochko's avatar
Eugen Rochko committed
48
- **Deployable via Docker**
Eugen Rochko's avatar
Eugen Rochko committed
49
  You don't need to mess with dependencies and configuration if you want to try Mastodon, if you have Docker and Docker Compose the deployment is extremely easy
Eugen Rochko's avatar
Eugen Rochko committed
50

51 52 53 54
## Configuration

- `LOCAL_DOMAIN` should be the domain/hostname of your instance. This is **absolutely required** as it is used for generating unique IDs for everything federation-related
- `LOCAL_HTTPS` set it to `true` if HTTPS works on your website. This is used to generate canonical URLs, which is also important when generating and parsing federation-related IDs
55

Eugen Rochko's avatar
Eugen Rochko committed
56
Consult the example configuration file, `.env.production.sample` for the full list. Among other things you need to set details for the SMTP server you are going to use.
Eugen Rochko's avatar
Eugen Rochko committed
57

58 59
## Requirements

60 61
- Ruby
- Node.js
62 63
- PostgreSQL
- Redis
64
- Nginx
65 66 67

## Running with Docker and Docker-Compose

68 69
[![](https://images.microbadger.com/badges/version/gargron/mastodon.svg)](https://microbadger.com/images/gargron/mastodon "Get your own version badge on microbadger.com") [![](https://images.microbadger.com/badges/image/gargron/mastodon.svg)](https://microbadger.com/images/gargron/mastodon "Get your own image badge on microbadger.com")

70
The project now includes a `Dockerfile` and a `docker-compose.yml` file (which requires at least docker-compose version `1.10.0`).
71

72
Review the settings in `docker-compose.yml`. Note that it is not default to store the postgresql database and redis databases in a persistent storage location,
73 74
so you may need or want to adjust the settings there.

75 76
Then, you need to fill in the `.env.production` file:

77
    cp .env.production.sample .env.production
78
    nano .env.production
79

80
Do NOT change the `REDIS_*` or `DB_*` settings when running with the default docker configurations.
81

82
You will need to fill in, at least: `LOCAL_DOMAIN`, `LOCAL_HTTPS`, `PAPERCLIP_SECRET`, `SECRET_KEY_BASE`, `OTP_SECRET`, and the `SMTP_*` settings.  To generate the `PAPERCLIP_SECRET`, `SECRET_KEY_BASE`, and `OTP_SECRET`, you may use:
83

84 85 86 87 88
Before running the first time, you need to build the images:

    docker-compose build


89
    docker-compose run --rm web rake secret
90

91
Do this once for each of those keys, and copy the result into the `.env.production` file in the appropriate field.
92

93
Then you should run the `db:migrate` command to create the database, or migrate it from an older release:
94

95
    docker-compose run --rm web rails db:migrate
96

97
Then, you will also need to precompile the assets:
98

99
    docker-compose run --rm web rails assets:precompile
100

101
before you can launch the docker image with:
102 103 104 105 106 107 108

    docker-compose up

If you wish to run this as a daemon process instead of monitoring it on console, use instead:

    docker-compose up -d

109
Then you may login to your new Mastodon instance by browsing to http://localhost:3000/
110 111

Following that, make sure that you read the [production guide](docs/Running-Mastodon/Production-guide.md). You are probably going to want to understand how
112
to configure Nginx to make your Mastodon instance available to the rest of the world.
113 114 115 116

The container has two volumes, for the assets and for user uploads, and optionally two more, for the postgresql and redis databases.

The default docker-compose.yml maps them to the repository's `public/assets` and `public/system` directories, you may wish to put them somewhere else. Likewise, the PostgreSQL and Redis images have data containers that you may wish to map somewhere where you know how to find them and back them up.
117

118 119 120 121 122 123 124
**Note**: The `--rm` option for docker-compose will remove the container that is created to run a one-off command after it completes. As data is stored in volumes it is not affected by that container clean-up.

### Tasks

- `rake mastodon:media:clear` removes uploads that have not been attached to any status after a while, you would want to run this from a periodic cronjob
- `rake mastodon:push:clear` unsubscribes from PuSH notifications for remote users that have no local followers. You may not want to actually do that, to keep a fuller footprint of the fediverse or in case your users will soon re-follow
- `rake mastodon:push:refresh` re-subscribes PuSH for expiring remote users, this should be run periodically from a cronjob and quite often as the expiration time depends on the particular hub of the remote user
Eugen Rochko's avatar
Eugen Rochko committed
125 126
- `rake mastodon:feeds:clear_all` removes all timelines, which forces them to be re-built on the fly next time a user tries to fetch their home/mentions timeline. Only for troubleshooting
- `rake mastodon:feeds:clear` removes timelines of users who haven't signed in lately, which allows to save RAM and improve message distribution. This is required to be run periodically so that when they login again the regeneration process will trigger
127 128 129 130 131

Running any of these tasks via docker-compose would look like this:

    docker-compose run --rm web rake mastodon:media:clear

132 133 134 135
### Updating

This approach makes updating to the latest version a real breeze.

136 137 138 139 140
1. `git pull` to download updates from the repository
2. `docker-compose build` to compile the Docker image out of the changed source files
3. (optional) `docker-compose run --rm web rails db:migrate` to perform database migrations. Does nothing if your database is up to date
4. (optional) `docker-compose run --rm web rails assets:precompile` to compile new JS and CSS assets
5. `docker-compose up -d` to re-create (restart) containers and pick up the changes
Eugen Rochko's avatar
Eugen Rochko committed
141

142 143
## Deployment without Docker

144
Docker is great for quickly trying out software, but it has its drawbacks too. If you prefer to run Mastodon without using Docker, refer to the [production guide](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Production-guide.md) for examples, configuration and instructions.
145

146 147
## Deployment on Scalingo

Jonathan Hurter's avatar
Jonathan Hurter committed
148
[![Deploy on Scalingo](https://cdn.scalingo.com/deploy/button.svg)](https://my.scalingo.com/deploy?source=https://github.com/tootsuite/mastodon#master)
149

150
[You can view a guide for deployment on Scalingo here.](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Scalingo-guide.md)
Jonathan Hurter's avatar
Add doc  
Jonathan Hurter committed
151

Effy Elden's avatar
Effy Elden committed
152 153 154 155
## Deployment on Heroku (experimental)

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)

156
Mastodon can run on [Heroku](https://heroku.com), but it gets expensive and impractical due to how Heroku prices resource usage. [You can view a guide for deployment on Heroku here](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Heroku-guide.md), but you have been warned.
Effy Elden's avatar
Effy Elden committed
157

158 159 160 161
## Development with Vagrant

A quick way to get a development environment up and running is with Vagrant. You will need recent versions of [Vagrant](https://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/) installed.

162
[You can find the guide for setting up a Vagrant development environment here.](https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Vagrant-guide.md)
163

164
## Contributing
Eugen Rochko's avatar
Eugen Rochko committed
165

166
You can open issues for bugs you've found or features you think are missing. You can also submit pull requests to this repository. [Here are the guidelines for code contributions](CONTRIBUTING.md)
167

Eugen Rochko's avatar
Eugen Rochko committed
168 169
**IRC channel**: #mastodon on irc.freenode.net

170
## Extra credits
171 172 173 174 175

- The [Emoji One](https://github.com/Ranks/emojione) pack has been used for the emojis
- The error page image courtesy of [Dopatwo](https://www.youtube.com/user/dopatwo)

![Mastodon error image](https://mastodon.social/oops.png)