Commit 2efc21ca authored by marcin mikołajczak's avatar marcin mikołajczak 💔

start Polish translation work

Signed-off-by: marcin mikołajczak's avatarMarcin Mikołajczak <me@m4sk.in>
parent 44281208
......@@ -13,6 +13,10 @@ enableGitInfo = true
contentDir = "content/en"
languageName = "English"
weight = 1
[languages.pl]
contentDir = "content/pl"
languageName = "Polski"
weight = 1
[menu]
[[menu.docs]]
......
---
title: Dokumentacja Mastodona
---
Witaj w dokumentacji Mastodona!
<div style="margin-bottom: 26px">
{{< youtube "IPSbNdBmWKE" >}}
</div>
**Wybierz swoją drogę:**
- [Dowiedz się jak korzystać z Mastodona]({{< relref "usage/basics.md" >}})
- [Dowiedz się jak zainstalować Mastodona]({{< relref "administration/installation.md" >}})
- [Dowiedz się jak napisać aplikację dla Mastodona]({{< relref "api/guidelines.md" >}})
---
title: Configuration
description: Overview of Mastodon's configuration options
menu:
docs:
parent: administration
weight: 2
---
Mastodon uses environment variables as its configuration.
For convenience, it can read them from a flat file called `.env.production` in the Mastodon directory, but they can always be overridden by a specific process. For example, systemd service files can read environment variables from an `EnvironmentFile` or from inline definitions with `Environment`, so you can have different configuration parameters for specific services. They can also be specified when calling Mastodon from the command line.
## Basic
### Federation
- `LOCAL_DOMAIN`
- `WEB_DOMAIN`
- `ALTERNATE_DOMAINS`
### Secrets
- `SECRET_KEY_BASE`
- `OTP_SECRET`
- `VAPID_PRIVATE_KEY`
- `VAPID_PUBLIC_KEY`
### Deployment
- `RAILS_ENV`
- `RAILS_SERVE_STATIC_FILES`
- `RAILS_LOG_LEVEL`
- `TRUSTED_PROXY_IP`
- `SOCKET`
- `PORT`
- `NODE_ENV`
- `BIND`
### Scaling options
- `WEB_CONCURRENCY`
- `MAX_THREADS`
- `PREPARED_STATEMENTS`
- `STREAMING_API_BASE_URL`
- `STREAMING_CLUSTER_NUM`
## Database connections
### PostgreSQL
- `DB_HOST`
- `DB_USER`
- `DB_NAME`
- `DB_PASS`
- `DB_PORT`
- `DATABASE_URL`
### Redis
- `REDIS_HOST`
- `REDIS_PORT`
- `REDIS_URL`
- `REDIS_NAMESPACE`
- `CACHE_REDIS_HOST`
- `CACHE_REDIS_PORT`
- `CACHE_REDIS_URL`
- `CACHE_REDIS_NAMESPACE`
### ElasticSearch
- `ES_ENABLED`
- `ES_HOST`
- `ES_PORT`
- `ES_PREFIX`
### StatsD
- `STATSD_ADDR`
- `STATSD_NAMESPACE`
## Limits
- `SINGLE_USER_MODE`
- `EMAIL_DOMAIN_WHITELIST`
- `DEFAULT_LOCALE`
- `MAX_SESSION_ACTIVATIONS`
- `USER_ACTIVE_DAYS`
## E-mail
- `SMTP_SERVER`
- `SMTP_PORT`
- `SMTP_LOGIN`
- `SMTP_PASSWORD`
- `SMTP_FROM_ADDRESS`
- `SMTP_DOMAIN`
- `SMTP_DELIVERY_METHOD`
- `SMTP_AUTH_METHOD`
- `SMTP_CA_FILE`
- `SMTP_OPENSSL_VERIFY_MODE`
- `SMTP_ENABLE_STARTTLS_AUTO`
- `SMTP_TLS`
## File storage
- `CDN_HOST`
- `S3_ALIAS_HOST`
### Local file storage
- `PAPERCLIP_ROOT_PATH`
- `PAPERCLIP_ROOT_URL`
### Amazon S3 and compatible
- `S3_ENABLED`
- `S3_BUCKET`
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `S3_REGION`
- `S3_PROTOCOL`
- `S3_HOSTNAME`
- `S3_ENDPOINT`
- `S3_SIGNATURE_VERSION`
### Swift
- `SWIFT_ENABLED`
- `SWIFT_USERNAME`
- `SWIFT_TENANT`
- `SWIFT_PASSWORD`
- `SWIFT_PROJECT_ID`
- `SWIFT_AUTH_URL`
- `SWIFT_CONTAINER`
- `SWIFT_OBJECT_URL`
- `SWIFT_REGION`
- `SWIFT_DOMAIN_NAME`
- `SWIFT_CACHE_TTL`
## External authentication
- `OAUTH_REDIRECT_AT_SIGN_IN`
### LDAP
- `LDAP_ENABLED`
- `LDAP_HOST`
- `LDAP_PORT`
- `LDAP_METHOD`
- `LDAP_BASE`
- `LDAP_BIND_DN`
- `LDAP_PASSWORD`
- `LDAP_UID`
- `LDAP_SEARCH_FILTER`
### PAM
- `PAM_ENABLED`
- `PAM_EMAIL_DOMAIN`
- `PAM_DEFAULT_SERVICE`
- `PAM_CONTROLLED_SERVICE`
### CAS
- `CAS_ENABLED`
- `CAS_URL`
- `CAS_HOST`
- `CAS_PORT`
- `CAS_SSL`
- `CAS_VALIDATE_URL`
- `CAS_CALLBACK_URL`
- `CAS_LOGOUT_URL`
- `CAS_LOGIN_URL`
- `CAS_UID_FIELD`
- `CAS_CA_PATH`
- `CAS_DISABLE_SSL_VERIFICATION`
- `CAS_UID_KEY`
- `CAS_NAME_KEY`
- `CAS_EMAIL_KEY`
- `CAS_NICKNAME_KEY`
- `CAS_FIRST_NAME_KEY`
- `CAS_LAST_NAME_KEY`
- `CAS_LOCATION_KEY`
- `CAS_IMAGE_KEY`
- `CAS_PHONE_KEY`
### SAML
- `SAML_ENABLED`
- `SAML_ACS_URL`
- `SAML_ISSUER`
- `SAML_IDP_SSO_TARGET_URL`
- `SAML_IDP_CERT`
- `SAML_IDP_CERT_FINGERPRINT`
- `SAML_NAME_IDENTIFIER_FORMAT`
- `SAML_CERT`
- `SAML_PRIVATE_KEY`
- `SAML_SECURITY_WANT_ASSERTION_SIGNED`
- `SAML_SECURITY_WANT_ASSERTION_ENCRYPTED`
- `SAML_SECURITY_ASSUME_EMAIL_IS_VERIFIED`
- `SAML_ATTRIBUTES_STATEMENTS_UID`
- `SAML_ATTRIBUTES_STATEMENTS_EMAIL`
- `SAML_ATTRIBUTES_STATEMENTS_FULL_NAME`
- `SAML_ATTRIBUTES_STATEMENTS_FIRST_NAME`
- `SAML_ATTRIBUTES_STATEMENTS_LAST_NAME`
- `SAML_UID_ATTRIBUTE`
- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED`
- `SAML_ATTRIBUTES_STATEMENTS_VERIFIED_EMAIL`
## Hidden services
- `http_proxy`
- `ALLOW_ACCESS_TO_HIDDEN_SERVICE`
## Other
- `SKIP_POST_DEPLOYMENT_MIGRATIONS`
---
title: Installation
description: How to install Mastodon on an Ubuntu 18.04 server
menu:
docs:
parent: administration
weight: 1
---
<img src="/setup.png" alt="" style="margin: 0; box-shadow: none">
## Basic server setup (optional)
If you are setting up a fresh machine, it is recommended that you secure it first. Assuming that you are running **Ubuntu 18.04**:
### Do not allow password-based SSH login (keys only)
First make sure you are actually logging in to the server using keys and not via a password, otherwise this will lock you out. Many hosting providers support uploading a public key and automatically set up key-based root login on new machines for you.
Edit `/etc/ssh/sshd_config` and find `PasswordAuthentication`. Make sure it's uncommented and set to `no`. If you made any changes, restart sshd:
```sh
systemctl restart ssh
```
### Update system packages
```sh
apt update && apt upgrade -y
```
### Install fail2ban so it blocks repeated login attempts
```sh
apt install fail2ban
```
Edit `/etc/fail2ban/jail.local` and put this inside:
```ini
[DEFAULT]
destemail = your@email.here
sendername = Fail2Ban
[sshd]
enabled = true
port = 22
[sshd-ddos]
enabled = true
port = 22
```
Finally restart fail2ban:
```sh
systemctl restart fail2ban
```
### Install a firewall and only whitelist SSH, HTTP and HTTPS ports
First, install iptables-persistent. During installation it will ask you if you want to keep current rules--decline.
```sh
apt install -y iptables-persistent
```
Edit `/etc/iptables/rules.v4` and put this inside:
```
*filter
# Allow all loopback (lo0) traffic and drop all traffic to 127/8 that doesn't use lo0
-A INPUT -i lo -j ACCEPT
-A INPUT ! -i lo -d 127.0.0.0/8 -j REJECT
# Accept all established inbound connections
-A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
# Allow all outbound traffic - you can modify this to only allow certain traffic
-A OUTPUT -j ACCEPT
# Allow HTTP and HTTPS connections from anywhere (the normal ports for websites and SSL).
-A INPUT -p tcp --dport 80 -j ACCEPT
-A INPUT -p tcp --dport 443 -j ACCEPT
# Allow SSH connections
# The -dport number should be the same port number you set in sshd_config
-A INPUT -p tcp -m state --state NEW --dport 22 -j ACCEPT
# Allow ping
-A INPUT -p icmp -m icmp --icmp-type 8 -j ACCEPT
# Log iptables denied calls
-A INPUT -m limit --limit 5/min -j LOG --log-prefix "iptables denied: " --log-level 7
# Reject all other inbound - default deny unless explicitly allowed policy
-A INPUT -j REJECT
-A FORWARD -j REJECT
COMMIT
```
With iptables-persistent, that configuration will be loaded at boot time. But since we are not rebooting right now, we need to load it manually for the first time:
```sh
iptables-restore < /etc/iptables/rules.v4
```
## Pre-requisites
- A machine running **Ubuntu 18.04** that you have root access to
- A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com`
- An e-mail delivery service or other **SMTP server**
You will be running the commands as root. If you aren't already root, switch to root:
```sh
sudo -i
```
### System repositories
Make sure curl is installed first:
```sh
apt install -y curl
```
#### Node.js
```sh
curl -sL https://deb.nodesource.com/setup_8.x | bash -
```
#### Yarn
```sh
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
```
### System packages
```sh
apt update
apt install -y \
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm5 libgdbm-dev \
nginx redis-server redis-tools postgresql postgresql-contrib \
certbot yarn libidn11-dev libicu-dev libjemalloc-dev
```
### Installing Ruby
We will be using rbenv to manage Ruby versions, because it's easier to get the right versions and to update once a newer release comes out. rbenv must be installed for a single Linux user, therefore, first we must create the user Mastodon will be running as:
```sh
adduser --disabled-login mastodon
```
We can then switch to the user:
```sh
su - mastodon
```
And proceed to install rbenv and rbenv-build:
```sh
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
```
Once this is done, we can install the correct Ruby version:
```sh
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.5.1
rbenv global 2.5.1
```
We'll also need to install bundler:
```sh
gem install bundler --no-ri --no-rdoc
```
Return to the root user:
```sh
exit
```
## Setup
### Setting up PostgreSQL
#### Performance configuration (optional)
For optimal performance, you may use [pgTune](https://pgtune.leopard.in.ua/#/) to generate an appropriate configuration and edit values in `/etc/postgresql/9.6/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
#### Creating a user
You will need to create a PostgreSQL user that Mastodon could use. It is easiest to go with "ident" authentication in a simple setup, i.e. the PostgreSQL user does not have a separate password and can be used by the Linux user with the same username.
Open the prompt:
```sh
sudo -u postgres psql
```
In the prompt, execute:
```
CREATE USER mastodon CREATEDB;
\q
```
Done!
### Setting up Mastodon
It is time to download the Mastodon code. Switch to the mastodon user:
```sh
su - mastodon
```
#### Checking out the code
Use git to download the latest stable release of Mastodon:
```sh
git clone https://github.com/tootsuite/mastodon.git live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
```
#### Installing the last dependencies
Now to install Ruby and JavaScript dependencies:
```sh
bundle install \
-j$(getconf _NPROCESSORS_ONLN) \
--deployment --without development test
yarn install --pure-lockfile
```
#### Generating a configuration
Run the interactive setup wizard:
```sh
RAILS_ENV=production bundle exec rake mastodon:setup
```
This will:
- Create a configuration file
- Run asset precompilation
- Create the database schema
The configuration file is saved as `.env.production`. You can review and edit it to your liking. Refer to the [documentation on configuration]({{< relref "configuration.md" >}}).
You're done with the mastodon user for now, so switch back to root:
```sh
exit
```
### Setting up nginx
Copy the configuration template for nginx from the Mastodon directory:
```sh
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
```
Then edit `/etc/nginx/sites-available/mastodon` to replace `example.com` with your own domain name, and make any other adjustments you might need.
Reload nginx for the changes to take effect:
```sh
systemctl reload nginx
```
### Acquiring a SSL certificate
We'll use Let's Encrypt to get a free SSL certificate:
```sh
certbot certonly --webroot -d example.com -w /home/mastodon/live/public/
```
You can now edit `/etc/nginx/sites-available/mastodon` to uncomment and adjust the `ssl_certificate` and `ssl_certificate_key` lines.
Then, reload nginx for the changes to take effect:
```sh
systemctl reload nginx
```
At this point you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven't started the Mastodon process yet.
### Setting up systemd services
Copy the systemd service templates from the Mastodon directory:
```sh
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
```
Then edit the files to make sure the username and paths are correct:
- `/etc/systemd/system/mastodon-web.service`
- `/etc/systemd/system/mastodon-sidekiq.service`
- `/etc/systemd/system/mastodon-streaming.service`
Finally, start and enable the new systemd services:
```sh
systemctl start mastodon-web mastodon-sidekiq mastodon-streaming
systemctl enable mastodon-*
```
They will now automatically start at boot time.
**Hurray! This is it. You can visit your domain in the browser now!**
---
title: Optional features
description: How to enable Mastodon's optional features
menu:
docs:
parent: administration
weight: 5
---
## Full-text search
TODO
## Hidden services
TODO
## Login via LDAP/PAM/CAS/SAML
TODO
---
title: Post-installation steps
description: What to do after the installation of Mastodon is complete
menu:
docs:
parent: administration
weight: 3
---
## 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 update 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|
|-------|-------|
|Contact username|Your username so people know who owns the server|
|Business e-mail|An e-mail address so people locked out of their accounts, or people without accounts, can contact you|
|Instance description|Why did you start this server? Who is it for? What makes it different?|
|Custom extended information|You can put all sorts of information in here but a **code of conduct** is recommended|
After you fill these in, simply hit "Save changes".
## Setting up regular backups (optional, but not really)
For any real-world use, you should make sure to regularly backup your Mastodon server.
### Overview
Things that need to be backed up in order of importance:
1. PostgreSQL database
2. Application secrets from the `.env.production` file or equivalent
3. User-uploaded files
4. Redis database
### Failure modes
There are two failure types that people in general may guard for: The failure of the hardware, such as data corruption on the disk; and human and software error, such as wrongful deletion of particular piece of data. In this documentation, only the former type is considered.
A lost PostgreSQL database is complete game over. Mastodon stores all the most important data in the PostgreSQL database. If the database disappears, all the accounts, posts and followers on your server will disappear with it.
If you lose application secrets, some functions of Mastodon will stop working for your users, they will be logged out, two-factor authentication will become unavailable, Web Push API subscriptions will stop working.
If you lose user-uploaded files, you will lose avatars, headers, and media attachments, but Mastodon *will* work moving forward.
Losing the Redis database is almost harmless: The only irrecoverable data will be the contents of the Sidekiq queues and scheduled retries of previously failed jobs. The home and list feeds are stored in Redis, but can be regenerated with tootctl.
The best backups are so-called off-site backups, i.e. ones that are not stored on the same machine as Mastodon itself. If the server you are hosted on goes on fire and the hard disk drive explodes, backups stored on that same hard drive won't be of much use.
### Backing up application secrets
Application secrets are the easiest to backup, since they never change. You only need to store `.env.production` somewhere safe.
### Backing up PostgreSQL
PostgreSQL is at risk of data corruption from power cuts, hard disk drive failure, and botched schema migrations. For that reason, occassionally making a backup with `pg_dump` or `pg_dumpall` is recommended.
For high-availability setups, it is possible to use hot streaming replication to have a second PostgreSQL server with always up-to-date data, ready to be switched over to if the other server goes down.
### Backing up user-uploaded files
If you are using an external object storage provider such as Amazon S3, Google Cloud or Wasabi, then you don't need to worry about backing those up. The respective companies are responsible for handling hardware failures.
If you are using local file storage, then it's up to you to make copies of the sizeable `public/system` directory, where uploaded files are stored by default.
### Backing up Redis
Backing up Redis is easy. Redis regularly writes to `/var/lib/redis/dump.rdb` which is the only file you need to make a copy of.
This diff is collapsed.
---
title: Upgrading to a new release
description: How to upgrade Mastodon to a newer version
menu:
docs:
parent: administration
weight: 5
---
When a new version of Mastodon comes out, it appears on the [GitHub releases page](https://github.com/tootsuite/mastodon/releases). Please mind that running unreleased code from the `master` branch, while possible, is not recommended.
Mastodon releases correspond to git tags. First, switch to the `mastodon` user:
```sh
su - mastodon
```
And navigate to the Mastodon root directory:
```sh
cd /home/mastodon/live
```