docs: use tabs and improve grammar in OTP install guide

This commit is contained in:
rinpatch 2019-12-09 20:09:47 +03:00
parent 0a8b32a661
commit 8dbe2dfde1

View file

@ -6,7 +6,7 @@
You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`. You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`.
While in theory OTP releases are possbile to install on any compatible machine, for the sake of simplicity this guide focuses only on Debian/Ubuntu/Alpine. While in theory OTP releases are possbile to install on any compatible machine, for the sake of simplicity this guide focuses only on Debian/Ubuntu and Alpine.
### Detecting flavour ### Detecting flavour
@ -20,6 +20,7 @@ If your platform is supported the output will contain the flavour string, you wi
### Installing the required packages ### Installing the required packages
Other than things bundled in the OTP release Pleroma depends on: Other than things bundled in the OTP release Pleroma depends on:
* curl (to download the release build) * curl (to download the release build)
* unzip (needed to unpack release builds) * unzip (needed to unpack release builds)
* ncurses (ERTS won't run without it) * ncurses (ERTS won't run without it)
@ -27,18 +28,16 @@ Other than things bundled in the OTP release Pleroma depends on:
* nginx (could be swapped with another reverse proxy but this guide covers only it) * nginx (could be swapped with another reverse proxy but this guide covers only it)
* certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it) * certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
Debian/Ubuntu: ```sh tab="Alpine"
```sh
apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot
```
Alpine:
```sh
echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
apk update apk update
apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot
``` ```
```sh tab="Debian/Ubuntu"
apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot
```
## Setup ## Setup
### Configuring PostgreSQL ### Configuring PostgreSQL
#### (Optional) Installing RUM indexes #### (Optional) Installing RUM indexes
@ -48,12 +47,7 @@ apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot
RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. You can read more about them on the [Configuration page](../configuration/cheatsheet.md#rum-indexing-for-full-text-search). They are completely optional and most of the time are not worth it, especially if you are running a single user instance (unless you absolutely need ordered search results). RUM indexes are an alternative indexing scheme that is not included in PostgreSQL by default. You can read more about them on the [Configuration page](../configuration/cheatsheet.md#rum-indexing-for-full-text-search). They are completely optional and most of the time are not worth it, especially if you are running a single user instance (unless you absolutely need ordered search results).
Debian/Ubuntu (available only on Buster/19.04): ```sh tab="Alpine"
```sh
apt install postgresql-11-rum
```
Alpine:
```sh
apk add git build-base postgresql-dev apk add git build-base postgresql-dev
git clone https://github.com/postgrespro/rum /tmp/rum git clone https://github.com/postgrespro/rum /tmp/rum
cd /tmp/rum cd /tmp/rum
@ -62,25 +56,31 @@ make USE_PGXS=1 install
cd cd
rm -r /tmp/rum rm -r /tmp/rum
``` ```
```sh tab="Debian/Ubuntu"
# Available only on Buster/19.04
apt install postgresql-11-rum
```
#### (Optional) Performance configuration #### (Optional) Performance configuration
For optimal performance, you may use [PGTune](https://pgtune.leopard.in.ua), don't forget to restart postgresql after editing the configuration For optimal performance, you may use [PGTune](https://pgtune.leopard.in.ua), don't forget to restart postgresql after editing the configuration
Debian/Ubuntu: ```sh tab="Alpine"
```sh
systemctl restart postgresql
```
Alpine:
```sh
rc-service postgresql restart rc-service postgresql restart
``` ```
```sh tab="Debian/Ubuntu"
systemctl restart postgresql
```
### Installing Pleroma ### Installing Pleroma
```sh ```sh
# Create the Pleroma user # Create a Pleroma user
adduser --system --shell /bin/false --home /opt/pleroma pleroma adduser --system --shell /bin/false --home /opt/pleroma pleroma
# Set the flavour environment variable to the string you got in Detecting flavour section. # Set the flavour environment variable to the string you got in Detecting flavour section.
# For example if the flavour is `arm64-musl` the command will be # For example if the flavour is `amd64-musl` the command will be
export FLAVOUR="arm64-musl" export FLAVOUR="amd64-musl"
# Clone the release build into a temporary directory and unpack it # Clone the release build into a temporary directory and unpack it
su pleroma -s $SHELL -lc " su pleroma -s $SHELL -lc "
@ -133,49 +133,52 @@ su pleroma -s $SHELL -lc "./bin/pleroma stop"
### Setting up nginx and getting Let's Encrypt SSL certificaties ### Setting up nginx and getting Let's Encrypt SSL certificaties
#### Get a Let's Encrypt certificate
```sh ```sh
# Get a Let's Encrypt certificate
certbot certonly --standalone --preferred-challenges http -d yourinstance.tld certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
```
# Copy the Pleroma nginx configuration to the nginx folder #### Copy Pleroma nginx configuration to the nginx folder
# The location of nginx configs is dependent on the distro
# For Debian/Ubuntu: The location of nginx configs is dependent on the distro
```sh tab="Alpine"
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
```
```sh tab="Debian/Ubuntu"
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx
ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
# For Alpine: ```
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
# If your distro does not have either of those you can append
# `include /etc/nginx/pleroma.conf` to the end of the http section in /etc/nginx/nginx.conf and
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
# Edit the nginx config replacing example.tld with your (sub)domain If your distro does not have either of those you can append `include /etc/nginx/pleroma.conf` to the end of the http section in /etc/nginx/nginx.conf and
```sh
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
```
#### Edit the nginx config
```sh
# Replace example.tld with your (sub)domain
$EDITOR path-to-nginx-config $EDITOR path-to-nginx-config
# Verify that the config is valid # Verify that the config is valid
nginx -t nginx -t
```
#### Start nginx
# Start nginx ```sh tab="Alpine"
# For Debian/Ubuntu:
systemctl start nginx
# For Alpine:
rc-service nginx start rc-service nginx start
``` ```
At this point if you open your (sub)domain in a browser you should see a 502 error, that's because pleroma is not started yet. ```sh tab="Debian/Ubuntu"
systemctl start nginx
```
At this point if you open your (sub)domain in a browser you should see a 502 error, that's because Pleroma is not started yet.
### Setting up a system service ### Setting up a system service
Debian/Ubuntu:
```sh
# Copy the service into a proper directory
cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
# Start pleroma and enable it on boot ```sh tab="Alpine"
systemctl start pleroma
systemctl enable pleroma
```
Alpine:
```sh
# Copy the service into a proper directory # Copy the service into a proper directory
cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
@ -184,13 +187,22 @@ rc-service pleroma start
rc-update add pleroma rc-update add pleroma
``` ```
```sh tab="Debian/Ubuntu"
# Copy the service into a proper directory
cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
# Start pleroma and enable it on boot
systemctl start pleroma
systemctl enable pleroma
```
If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errrors. If everything worked, you should see Pleroma-FE when visiting your domain. If that didn't happen, try reviewing the installation steps, starting Pleroma in the foreground and seeing if there are any errrors.
Still doesn't work? Feel free to contact us on [#pleroma on freenode](https://webchat.freenode.net/?channels=%23pleroma) or via matrix at <https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org>, you can also [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma/issues/new) Still doesn't work? Feel free to contact us on [#pleroma on freenode](https://irc.pleroma.social) or via matrix at <https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org>, you can also [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma-support/issues/new)
## Post installation ## Post installation
### Setting up auto-renew Let's Encrypt certificate ### Setting up auto-renew of the Let's Encrypt certificate
```sh ```sh
# Create the directory for webroot challenges # Create the directory for webroot challenges
mkdir -p /var/lib/letsencrypt mkdir -p /var/lib/letsencrypt
@ -201,25 +213,8 @@ $EDITOR path-to-nginx-config
# Verify that the config is valid # Verify that the config is valid
nginx -t nginx -t
``` ```
Debian/Ubuntu:
```sh
# Restart nginx
systemctl restart nginx
# Ensure the webroot menthod and post hook is working ```sh tab="Alpine"
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl nginx reload'
# Add it to the daily cron
echo '#!/bin/sh
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
' > /etc/cron.daily/renew-pleroma-cert
chmod +x /etc/cron.daily/renew-pleroma-cert
# If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
run-parts --test /etc/cron.daily
```
Alpine:
```sh
# Restart nginx # Restart nginx
rc-service nginx restart rc-service nginx restart
@ -236,15 +231,25 @@ certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --
' > /etc/periodic/daily/renew-pleroma-cert ' > /etc/periodic/daily/renew-pleroma-cert
chmod +x /etc/periodic/daily/renew-pleroma-cert chmod +x /etc/periodic/daily/renew-pleroma-cert
# If everything worked this should output /etc/periodic/daily/renew-pleroma-cert # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
run-parts --test /etc/periodic/daily run-parts --test /etc/periodic/daily
``` ```
### Running mix tasks
Throughout the wiki and guides there is a lot of references to mix tasks. Since `mix` is a build tool, you can't just call `mix pleroma.task`, instead you should call `pleroma_ctl` stripping pleroma/ecto namespace.
So for example, if the task is `mix pleroma.user set admin --admin`, you should run it like this: ```sh tab="Debian/Ubuntu"
```sh # Restart nginx
su pleroma -s $SHELL -lc "./bin/pleroma_ctl user set admin --admin" systemctl restart nginx
# Ensure the webroot menthod and post hook is working
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl reload nginx'
# Add it to the daily cron
echo '#!/bin/sh
certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
' > /etc/cron.daily/renew-pleroma-cert
chmod +x /etc/cron.daily/renew-pleroma-cert
# If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
run-parts --test /etc/cron.daily
``` ```
## Create your first user and set as admin ## Create your first user and set as admin
@ -270,4 +275,3 @@ But you should **always check the release notes/changelog** in case there are co
* [Backup your instance](../administration/backup.md) * [Backup your instance](../administration/backup.md)
* [Hardening your instance](../configuration/hardening.md) * [Hardening your instance](../configuration/hardening.md)
* [How to activate mediaproxy](../configuration/howto_mediaproxy.md) * [How to activate mediaproxy](../configuration/howto_mediaproxy.md)
* [Updating your instance](../administration/updating.md)