Commit 1398a4d9 authored by Eugen Rochko's avatar Eugen Rochko

Update documentation with contents by twrnh

parent 88e18a4e
image: registry.gitlab.com/pages/hugo:latest
image: monachus/hugo:latest
variables:
GIT_SUBMODULE_STRATEGY: recursive
......
(function () {
'use strict';
const onLoaded = () => {
// Nothing for now
};
if (['interactive', 'complete'].indexOf(document.readyState) !== -1) {
onLoaded();
} else {
document.addEventListener('DOMContentLoaded', onLoaded);
}
})();
@import url('https://fonts.googleapis.com/css?family=Montserrat:400,600|Roboto:400,500,700|Roboto+Mono:400');
@import url('https://unpkg.com/ionicons@4.2.0/dist/css/ionicons.min.css');
@import 'fontawesome.scss';
$white: #fff ; // color5
$lightest: #d9e1e8; // color2
......@@ -123,13 +123,11 @@ body {
justify-content: flex-start;
align-items: center;
color: $darkest;
margin-top: 12px;
margin-bottom: 52px;
img {
height: 38px;
position: relative;
left: -14px;
top: -4px;
}
@media screen and (max-width: $mobile-width) {
......@@ -141,30 +139,26 @@ body {
}
}
a {
display: inline-block;
color: $lighter;
text-decoration: none;
font-size: 14px;
padding: 10px 0;
& > ul > li {
margin-bottom: 26px;
}
&:hover,
&:focus,
&:active {
color: lighten($lighter, 8%);
}
.sub-title {
display: block;
padding: 10px;
font-weight: 500;
text-transform: uppercase;
}
& > ul > li > a {
font-size: 18px;
font-family: 'Montserrat', sans-serif;
font-weight: 600;
padding-bottom: 26px;
& > ul a {
display: block;
color: $white;
text-decoration: none;
font-weight: 500;
padding: 10px;
}
.sub-menu {
padding-bottom: 26px;
a.active {
color: $vibrant;
}
......@@ -172,6 +166,10 @@ body {
&.collapsed {
display: none;
}
.sub-menu {
padding-left: 15px;
}
}
}
......@@ -424,6 +422,10 @@ main {
overflow: auto;
}
figure pre {
margin-bottom: 0;
}
code {
padding: 0.2em 0.4em;
margin: 0;
......@@ -569,3 +571,205 @@ main {
}
}
}
.hint {
margin: 26px 0;
padding: 16px 16px 16px 56px;
position: relative;
border-left: 4px solid;
border-radius: 4px;
background-color: lighten($darkest, 8%);
color: $white;
font-size: 16px;
line-height: 28px;
&-info {
border-color: $vibrant;
.hint-icon {
color: $vibrant;
}
}
&-warning {
border-color: #ca8f04;
.hint-icon {
color: #ca8f04;
}
}
&-success {
border-color: $success;
.hint-icon {
color: $success;
}
}
&-danger {
border-color: $error;
.hint-icon {
color: $error;
}
}
&-icon {
position: absolute;
top: 18px;
left: 16px;
font-size: 24px;
}
}
.page-ref {
display: block;
background: lighten($darkest, 4%);
color: $vibrant;
text-decoration: none;
font-weight: 500;
font-size: 18px;
position: relative;
margin: 26px 0;
padding: 24px 24px 24px 50px;
border-radius: 4px;
&-icon {
position: absolute;
top: 20px;
left: 16px;
font-size: 24px;
}
&:hover,
&:focus,
&:active {
background: lighten($darkest, 8%);
}
}
.api-method {
display: flex;
align-items: center;
font-weight: 500;
font-size: 18px;
&-method {
display: inline-flex;
align-items: center;
padding: 2px 0;
border-radius: 9999px;
height: 21px;
color: $white;
background: $vibrant;
margin: 0;
margin-right: 8px;
span {
display: inline-block;
padding: 0 8px;
font-size: 12px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 1px;
line-height: 15px;
}
}
&-url {
background: lighten($darkest, 4%);
border-radius: 4px;
padding: 8px;
font-size: 16px;
margin: 26px 0;
line-height: 1.7;
}
&-host {
color: $darker;
}
&-path {
font-weight: 700;
color: $white;
}
}
.api-method-parameters-list {
border: 1px solid lighten($darkest, 8%);
border-radius: 4px;
margin-bottom: 26px;
}
.api-method-parameters-type {
font-weight: 400;
color: $darker;
}
.api-method-parameters-type,
.api-method-response-example h5 {
font-size: 16px;
margin-bottom: 16px;
}
.api-method-parameter {
display: flex;
border-bottom: 1px solid lighten($darkest, 8%);
&:last-child {
border-bottom: 0;
}
&-cell {
box-sizing: border-box;
padding: 16px 10px;
color: $white;
}
&-required {
text-transform: uppercase;
font-size: 12px;
font-weight: 500;
color: $error;
}
&-optional {
text-transform: uppercase;
font-size: 12px;
font-weight: 500;
color: $darker;
}
&-name {
width: 180px;
font-size: 16px;
& > div:first-child {
margin-bottom: 2px;
}
}
&-type {
width: 100px;
}
&-description {
flex: 1 1 0%;
font-size: 15px;
}
}
.api-method-response-example {
&-indicator {
display: inline-block;
width: 12px;
height: 12px;
border-radius: 50%;
background: $success;
&-error {
background: $error;
}
}
}
......@@ -8,69 +8,50 @@ metaDataFormat = "yaml"
paginate = 100
enableGitInfo = true
[languages]
[languages.en]
contentDir = "content/en"
languageName = "English"
weight = 1
[languages.pl]
contentDir = "content/pl"
languageName = "Polski"
weight = 1
[languages.fr]
contentDir = "content/fr"
languageName = "Français"
weight = 1
[languages.fr.menu]
[[languages.fr.menu.docs]]
name = "Guide d'utilisation"
weight = 1
identifier = "usage"
url = "/usage/"
[[languages.fr.menu.docs]]
name = "Guide d'administration"
weight = 2
identifier = "administration"
url = "/administration/"
[[languages.fr.menu.docs]]
name = "Guide de développement"
weight = 3
identifier = "development"
url = "/development/"
[[languages.fr.menu.docs]]
name = "Aperçu de l'API"
weight = 4
identifier = "api"
url = "/api/"
[[languages.fr.menu.docs]]
name = "API REST"
weight = 5
identifier = "rest-api"
url = "/api/rest/"
[menu]
[[menu.docs]]
name = "User guide"
weight = 1
identifier = "usage"
url = "/usage/"
name = "Using Mastodon"
weight = 10
identifier = "user"
url = "/user/"
[[menu.docs]]
name = "Running Mastodon"
weight = 20
identifier = "admin"
url = "/admin/"
[[menu.docs]]
name = "Developing Mastodon apps"
weight = 30
identifier = "client"
url = "/client/"
[[menu.docs]]
name = "Contributing to Mastodon"
weight = 40
identifier = "dev"
url = "/dev/"
[[menu.docs]]
name = "Administrator guide"
weight = 2
identifier = "administration"
url = "/administration/"
name = "Spec compliance"
weight = 50
identifier = "spec"
url = "/spec/"
[[menu.docs]]
name = "API Overview"
weight = 4
name = "REST API"
weight = 60
identifier = "api"
url = "/api/"
[[menu.docs]]
name = "REST API"
weight = 5
identifier = "rest-api"
url = "/api/rest/"
name = "API Methods"
weight = 70
identifier = "methods"
url = "/methods/"
[[menu.docs]]
name = "Development guide"
weight = 3
identifier = "development"
url = "/development/"
\ No newline at end of file
name = "API Entities"
weight = 80
identifier = "entities"
url = "/entities/"
[languages]
[languages.en]
contentDir = "content/en"
languageName = "English"
weight = -99
---
title: Mastodon documentation
title: What is Mastodon?
description: Welcome to the Mastodon documentation!
menu:
docs:
weight: -99
---
Welcome to the Mastodon documentation!
{{< youtube id="IPSbNdBmWKE" caption="An introductory video explaining basic Mastodon concepts with visual animations" >}}
## What is a microblog?
Similar to how blogging is the act of publishing updates to a website, **microblogging** is the act of publishing small updates to a stream of updates on your profile. You can publish text posts and optionally attach media such as pictures, audio, video, or polls. Mastodon lets you follow friends and discover new ones.
## What is federation? <a id="what-is-federation"></a>
**Federation** is a form of decentralization. Instead of a single central service that all people use, there are multiple services, that any number of people can use.
| Grade of centralization | Examples |
| :--- | :--- |
| Centralized | Twitter, Facebook, Instagram |
| Federated | Email, XMPP, phone networks, physical mail |
| Distributed | BitTorrent, IPFS, Scuttlebutt |
A Mastodon website can operate alone. Just like a traditional website, people sign up on it, post messages, upload pictures and talk to each other. _Unlike_ a traditional website, Mastodon websites can interoperate, letting their users communicate with each other; just like you can send an email from your Gmail account to someone from Outlook, Fastmail, Protonmail, or any other email provider, as long as you know their email address, **you can mention or message anyone on any website using their address**.
{{< figure src="/assets/image%20%289%29.png" caption="From left to right: Centralized, Federated, Distributed" >}}
## What is ActivityPub? <a id="the-fediverse"></a>
Mastodon uses a standardized, open protocol to implement federation. It is called **ActivityPub**. Any software that likewise implements federation via ActivityPub can seamlessly communicate with Mastodon, just like Mastodon websites communicate with one another.
The **fediverse** \(“federated universe”\) is the name for all websites that can communicate with each other over ActivityPub and the World Wide Web. That includes all Mastodon servers, but also other implementations:
* Pleroma, a modular microblogging engine,
* Pixelfed, which lets you share and consume media posts,
* Misskey, which includes microblogging alongside a customizable dashboard,
* PeerTube, which lets you upload videos to channels,
* Plume, which lets you publish longer-form articles,
* and many more, including individual and personal websites!
The fediverse does not have its own brand, so you might more often hear “follow me on Mastodon” than “follow me on the fediverse”, but technically the latter is more correct.
## Practical implications <a id="practical-implications"></a>
### Choice of service provider and policy
Because Mastodon is simply software that can be used to power any website, potential users of Mastodon have the option of choosing a service provider from already-existing Mastodon websites, or to create their own Mastodon website if they wish. The Mastodon project maintains a list of recommended service providers at [joinmastodon.org](https://joinmastodon.org), sortable by category and/or language. Some websites may have moderation policies that go beyond this, such as requiring the use of certain tags on potentially sensitive content, and some websites may have more relaxed moderation policies, but websites listed in the picker all agree to adopt the [Mastodon Server Covenant](https://joinmastodon.org/covenant), meaning that they pledge to actively moderate against hate speech, to take daily backups, to have at least one emergency admin, and to provide at least 3 months advance notice in case of shutdown.
> Maintaining communities that feel safe for all of its members is not easy. Mastodon provides a lot of foundational framework and tools for doing it, and shifts the power to effect change from one commercial entity to the communities themselves.
>
> -- Eugen Rochko, Jul 6 2018, ["Cage the Mastodon"](https://blog.joinmastodon.org/2018/07/cage-the-mastodon/)
> A centralized social media platform has a hierarchical structure where rules and their enforcement, as well as the development and direction of the platform, are decided by the CEO \[...\] A decentralized network deliberately relinquishes control of the platform owner, by essentially not having one.
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
### Funding and monetization <a id="funding-and-monetization"></a>
Mastodon websites are operated by different people or organizations completely independently. Mastodon does not implement any monetization strategies in the software.
Some server operators choose to offer paid accounts, some server operators are companies who can utilize their existing infrastructure, some server operators rely on crowdfunding from their users via Patreon and similar services, and some server operators are just paying out-of-pocket for a personal server for themselves and maybe some friends. So if you want to support the server hosting your account, check if it offers a way to donate.
Mastodon development is likewise crowdfunded via [Patreon](https://patreon.com/mastodon) and via [OpenCollective](https://opencollective.com/mastodon). **No venture capital is involved.**
> In my opinion, “instant, public, global messaging and conversation” should, in fact, be _global_. Distributed between independent organizations and actors who can self-govern. A public utility, without incentives to exploit the conversations for profit.
>
> -- Eugen Rochko, Mar 3 2018, ["Twitter is not a public utility"](https://blog.joinmastodon.org/2018/03/twitter-is-not-a-public-utility/)
### Interoperability between different software <a id="impersonation-and-verification"></a>
In practical terms: Imagine if you could follow an Instagram user from your Twitter account and comment on their photos without leaving your account. If Twitter and Instagram were federated services that used the same protocol, that would be possible. With a Mastodon account, **you can communicate with any other compatible website,** _**even if it is not running on Mastodon**_. All that is necessary is that the software support the same subset of the ActivityPub protocol that allows for creating and interacting with status updates. To find out more about the technical specifications required to interoperate with Mastodon, see [ActivityPub](spec/activitypub.md), [WebFinger](spec/webfinger.md), and [Security](spec/security.md). To read more about what ActivityPub allows us to do, see [Why ActivityPub is the future](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/).
> All of these platforms are different and they focus on different needs. And yet, the foundation is all the same: people subscribing to receive posts from other people. And so, they are all compatible.
>
> -- Eugen Rochko, Jun 27 2018, ["Why ActivityPub is the future"](https://blog.joinmastodon.org/2018/06/why-activitypub-is-the-future/)
### Free/libre software
Unlike proprietary services, **anyone has the complete freedom to run, examine, inspect, copy, modify, distribute, and reuse the Mastodon source code, provided they guarantee the same freedoms for any derivative work.** Just like how users of Mastodon can choose their service provider, you as an individual are free to contribute features to Mastodon or publish a modified version of Mastodon that includes different features. These modified versions, also known as software forks, are required to also uphold the same freedoms as the original Mastodon project. For example, [glitch-soc](https://glitch-soc.github.io/docs/) is a software distribution that adds various experimental features. Many individual forks exist as well, perhaps themed slightly differently or including small modifications to the codebase. Because Mastodon is libre software that respects your freedom, personalizations like this are not only allowed but encouraged.
> The ultimate power is in giving people the ability to create their own spaces, their own communities, to modify the software as they see fit, but without sacrificing the ability of people from different communities to interact with each other.
>
> -- Eugen Rochko, Feb 20 2017, ["The power to build communities: A response to Mark Zuckerberg"](https://blog.joinmastodon.org/2017/02/the-power-to-build-communities/)
> Decentralization is biodiversity of the digital world, the hallmark of a healthy ecosystem. A decentralized network like the fediverse allows different user interfaces, different software, different forms of government to co-exist and cooperate.
>
> -- Eugen Rochko, Dec 30 2018, ["Why does decentralization matter?"](https://blog.joinmastodon.org/2018/12/why-does-decentralization-matter/)
## Choose your path
![](/assets/elephant.svg)
Learn how to use Mastodon:
{{< page-ref page="user/signup.md" >}}
Learn how to install Mastodon:
{{< page-ref page="admin/prerequisites.md" >}}
Learn how to write an app for Mastodon:
{{< page-ref page="client/intro.md" >}}
Learn about the Mastodon backend and how to contribute:
{{< page-ref page="dev/overview.md" >}}
<div style="margin-bottom: 26px">
{{< youtube "IPSbNdBmWKE" >}}
</div>
**Choose your path:**
- [Learn how to use Mastodon]({{< relref "usage/basics.md" >}})
- [Learn how to install Mastodon]({{< relref "administration/installation.md" >}})
- [Learn how to write an app for Mastodon]({{< relref "api/guidelines.md" >}})
---
title: Post-installation steps
description: What to do after the installation of Mastodon is complete
title: Backing up your server
menu:
docs:
parent: administration
weight: 3
weight: 80
parent: admin
---
## Using the command-line interface
The command-line interface of Mastodon is an executable file called `tootctl` residing in the `bin` directory within the Mastodon root directory. You must specify which environment you intend to use whenever you execute it by specifying the `RAILS_ENV` environment variable. Unless you are a developer working on a local machine, you need to use `RAILS_ENV=production`. If you are sure that you will never need another environment (for development, testing, or staging), you can add it to your `.bashrc` file for convenience, e.g.:
```bash
echo "export RAILS_ENV=production" >> ~/.bashrc
```
If so, you won't need to specify it each time inline. Otherwise, calls to `tootctl` will usually go like this, assuming that the Mastodon code is checked out in `/home/mastodon/live`:
```bash
cd /home/mastodon/live
RAILS_ENV=production bin/tootctl help
```
## Creating an admin account
### In the browser
After signing up in the browser, you will need to use the command line to give your newly created account admin privileges. Assuming your username is `alice`:
```bash
RAILS_ENV=production bin/tootctl accounts modify alice --role admin
```
### From the command line
You can create a new account using the command-line interface.
```bash
RAILS_ENV=production bin/tootctl accounts create \
alice \
--email alice@example.com \
--confirmed \
--role admin
```
A randomly generated password will be shown in the terminal.
## Filling in server information
After logging in, navigate to the **Site settings** page. While there are no technical requirements for filling in this information, it is considered crucial for operating a server for humans.
|Setting|Meaning|
|-------|-------|