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
### 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)
* 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
-echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
-apk update
-apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot
-```
+=== "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
+ ```
+
+=== "Debian/Ubuntu"
+ ```
+ apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot
+ ```
+
+### Installing optional packages
+
+Per [`docs/installation/optional/media_graphics_packages.md`](docs/installation/optional/media_graphics_packages.md):
+ * ImageMagick
+ * ffmpeg
+ * exiftool
+
+=== "Alpine"
+ ```
+ echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
+ apk update
+ apk add imagemagick ffmpeg exiftool
+ ```
+
+=== "Debian/Ubuntu"
+ ```
+ apt install imagemagick ffmpeg libimage-exiftool-perl
+ ```
## Setup
### Configuring PostgreSQL
#### (Optional) Installing RUM indexes
+
+!!! warning
+ It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
+
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
-apk add git build-base postgresql-dev
-git clone https://github.com/postgrespro/rum /tmp/rum
-cd /tmp/rum
-make USE_PGXS=1
-make USE_PGXS=1 install
-cd
-rm -r /tmp/rum
-```
+=== "Alpine"
+ ```
+ apk add git build-base postgresql-dev
+ git clone https://github.com/postgrespro/rum /tmp/rum
+ cd /tmp/rum
+ make USE_PGXS=1
+ make USE_PGXS=1 install
+ cd
+ rm -r /tmp/rum
+ ```
+
+=== "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
+It is encouraged to check [Optimizing your PostgreSQL performance](../configuration/postgresql.md) document, for tips on PostgreSQL tuning.
-Debian/Ubuntu:
-```sh
-systemctl restart postgresql
-```
-Alpine:
-```sh
-rc-service postgresql restart
+=== "Alpine"
+ ```
+ rc-service postgresql restart
+ ```
+
+=== "Debian/Ubuntu"
+ ```
+ systemctl restart postgresql
+ ```
+
+If you are using PostgreSQL 12 or higher, add this to your Ecto database configuration
+
+```elixir
+prepare: :named,
+parameters: [
+ plan_cache_mode: "force_custom_plan"
+]
```
+
### 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"
+# Set the flavour environment variable to the string you got in Detecting flavour section.
+# 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 "
### 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 Pleroma nginx configuration to the nginx folder
-# Copy the Pleroma nginx configuration to the nginx folder
-# The location of nginx configs is dependent on the distro
+The location of nginx configs is dependent on the distro
-# For 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
+=== "Alpine"
+ ```
+ cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
+ ```
+
+=== "Debian/Ubuntu"
+ ```
+ cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf
+ ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/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
+```sh
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
+```
-# Edit the nginx config replacing example.tld with your (sub)domain
+#### 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
-# For Debian/Ubuntu:
-systemctl start nginx
-# For Alpine:
-rc-service nginx start
```
+#### 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.
+=== "Alpine"
+ ```
+ rc-service nginx start
+ ```
+
+=== "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
-# Copy the service into a proper directory
-cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
+=== "Alpine"
+ ```
+ # Copy the service into a proper directory
+ cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
-# Start pleroma and enable it on boot
-rc-service pleroma start
-rc-update add pleroma
-```
+ # Start pleroma and enable it on boot
+ rc-service pleroma start
+ rc-update add 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.
+=== "Debian/Ubuntu"
+ ```
+ # Copy the service into a proper directory
+ cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
-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)
+ # 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://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
-### 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
# 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'
+=== "Alpine"
+ ```
+ # Restart nginx
+ rc-service nginx restart
-# 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
+ # Start the cron daemon and make it start on boot
+ rc-service crond start
+ rc-update add crond
-# If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
-run-parts --test /etc/cron.daily
-```
-Alpine:
-```sh
-# Restart nginx
-rc-service nginx restart
+ # Ensure the webroot menthod and post hook is working
+ certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'rc-service nginx reload'
-# Start the cron daemon and make it start on boot
-rc-service crond start
-rc-update add crond
+ # Add it to the daily cron
+ echo '#!/bin/sh
+ certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "rc-service nginx reload"
+ ' > /etc/periodic/daily/renew-pleroma-cert
+ chmod +x /etc/periodic/daily/renew-pleroma-cert
-# Ensure the webroot menthod and post hook is working
-certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'rc-service nginx reload'
+ # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
+ run-parts --test /etc/periodic/daily
+ ```
-# Add it to the daily cron
-echo '#!/bin/sh
-certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "rc-service nginx reload"
-' > /etc/periodic/daily/renew-pleroma-cert
-chmod +x /etc/periodic/daily/renew-pleroma-cert
+=== "Debian/Ubuntu"
+ ```
+ # Restart nginx
+ systemctl restart nginx
-# If everything worked this should output /etc/periodic/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.
+ # 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'
-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"
-```
+ # 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
```sh
```
This will create an account withe the username of 'joeuser' with the email address of joeuser@sld.tld, and set that user's account as an admin. This will result in a link that you can paste into the browser, which logs you in and enables you to set the password.
-### Updating
-Generally, doing the following is enough:
-```sh
-# Download the new release
-su pleroma -s $SHELL -lc "./bin/pleroma_ctl update"
+## Further reading
-# Migrate the database, you are advised to stop the instance before doing that
-su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
-```
-But you should **always check the release notes/changelog** in case there are config deprecations, special update steps, etc.
+{! backend/installation/further_reading.include !}
-## Further reading
+## Questions
+
+Questions about the installation or didn’t it work as it should be, ask in [#pleroma:matrix.org](https://matrix.heldscal.la/#/room/#freenode_#pleroma:matrix.org) or IRC Channel **#pleroma** on **Freenode**.
-* [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)
projects / akkoma / blobdiff