From 8dbe2dfde1b606ec7dd5461cee89ad1b4e7ca39c Mon Sep 17 00:00:00 2001 From: rinpatch Date: Mon, 9 Dec 2019 20:09:47 +0300 Subject: [PATCH] docs: use tabs and improve grammar in OTP install guide --- docs/installation/otp_en.md | 154 ++++++++++++++++++------------------ 1 file changed, 79 insertions(+), 75 deletions(-) diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md index 965e30e2a..93230806c 100644 --- a/docs/installation/otp_en.md +++ b/docs/installation/otp_en.md @@ -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`. -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 @@ -20,6 +20,7 @@ If your platform is supported the output will contain the flavour string, you wi ### Installing the required packages Other than things bundled in the OTP release Pleroma depends on: + * curl (to download the release build) * unzip (needed to unpack release builds) * 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) * certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it) -Debian/Ubuntu: -```sh -apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot -``` -Alpine: - -```sh +```sh tab="Alpine" echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories apk update 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 ### Configuring PostgreSQL #### (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). -Debian/Ubuntu (available only on Buster/19.04): -```sh -apt install postgresql-11-rum -``` -Alpine: -```sh +```sh tab="Alpine" apk add git build-base postgresql-dev git clone https://github.com/postgrespro/rum /tmp/rum cd /tmp/rum @@ -62,25 +56,31 @@ make USE_PGXS=1 install cd rm -r /tmp/rum ``` + +```sh tab="Debian/Ubuntu" +# Available only on Buster/19.04 +apt install postgresql-11-rum +``` + #### (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 -Debian/Ubuntu: -```sh -systemctl restart postgresql -``` -Alpine: -```sh +```sh tab="Alpine" rc-service postgresql restart ``` + +```sh tab="Debian/Ubuntu" +systemctl restart postgresql +``` + ### Installing Pleroma ```sh -# Create the Pleroma user +# Create a Pleroma user adduser --system --shell /bin/false --home /opt/pleroma pleroma # 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 -export FLAVOUR="arm64-musl" +# For example if the flavour is `amd64-musl` the command will be +export FLAVOUR="amd64-musl" # Clone the release build into a temporary directory and unpack it 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 +#### Get a Let's Encrypt certificate ```sh -# Get a Let's Encrypt certificate certbot certonly --standalone --preferred-challenges http -d yourinstance.tld +``` -# Copy the Pleroma nginx configuration to the nginx folder -# The location of nginx configs is dependent on the distro +#### Copy Pleroma nginx configuration to the nginx folder -# 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 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 # Verify that the config is valid nginx -t +``` +#### Start nginx -# Start nginx -# For Debian/Ubuntu: -systemctl start nginx -# For Alpine: +```sh tab="Alpine" 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 -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 -systemctl start pleroma -systemctl enable pleroma -``` -Alpine: -```sh +```sh tab="Alpine" # Copy the service into a proper directory cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma @@ -184,13 +187,22 @@ rc-service pleroma start 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. -Still doesn't work? Feel free to contact us on [#pleroma on freenode](https://webchat.freenode.net/?channels=%23pleroma) or via matrix at , 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 , you can also [file an issue on our Gitlab](https://git.pleroma.social/pleroma/pleroma-support/issues/new) ## Post installation -### Setting up auto-renew Let's Encrypt certificate +### Setting up auto-renew of the Let's Encrypt certificate ```sh # Create the directory for webroot challenges mkdir -p /var/lib/letsencrypt @@ -201,25 +213,8 @@ $EDITOR path-to-nginx-config # Verify that the config is valid nginx -t ``` -Debian/Ubuntu: -```sh -# Restart nginx -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 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 +```sh tab="Alpine" # Restart nginx 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 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 ``` -### 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 -su pleroma -s $SHELL -lc "./bin/pleroma_ctl user set admin --admin" +```sh tab="Debian/Ubuntu" +# Restart nginx +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 @@ -270,4 +275,3 @@ But you should **always check the release notes/changelog** in case there are co * [Backup your instance](../administration/backup.md) * [Hardening your instance](../configuration/hardening.md) * [How to activate mediaproxy](../configuration/howto_mediaproxy.md) -* [Updating your instance](../administration/updating.md)