2019-06-21 02:48:13 +00:00
# Installing on Linux using OTP releases
2021-08-10 06:09:31 +00:00
{! backend/installation/otp_vs_from_source.include !}
2023-03-05 07:41:15 +00:00
This guide covers a installation using OTP releases as built by the Pleroma project, it is meant as a fallback to distribution packages/recipes which are the preferred installation method.
To install Pleroma from source, please check out the corresponding guide for your distro.
2021-08-10 06:09:31 +00:00
2019-06-21 02:48:13 +00:00
## Pre-requisites
2023-03-05 07:41:15 +00:00
* A machine you have root access to running Debian GNU/Linux or compatible (eg. Ubuntu), or Alpine on `x86_64` , `aarch64` or `armv7l` CPU. If you are not sure what you are running see [Detecting flavour section ](#detecting-flavour ) below
2019-06-21 02:48:13 +00:00
* A (sub)domain pointed to the machine
2023-03-05 07:41:15 +00:00
You will be running commands as root. If you aren't root already, please elevate your privileges by executing `sudo -i` /`su`.
2019-06-21 02:48:13 +00:00
2023-03-05 07:41:15 +00:00
Similarly to other binaries, OTP releases tend to be only compatible with the distro they are built on, as such this guide focuses only on Debian/Ubuntu and Alpine.
2019-06-21 02:48:13 +00:00
### Detecting flavour
Paste the following into the shell:
```sh
2019-06-22 05:30:32 +00:00
arch="$(uname -m)";if [ "$arch" = "x86_64" ];then arch="amd64";elif [ "$arch" = "armv7l" ];then arch="arm";elif [ "$arch" = "aarch64" ];then arch="arm64";else echo "Unsupported arch: $arch">&2; fi;if getconf GNU_LIBC_VERSION>/dev/null;then libc_postfix="";elif [ "$(ldd 2>& 1|head -c 9)" = "musl libc" ];then libc_postfix="-musl";elif [ "$(find /lib/libc.musl*|wc -l)" ];then libc_postfix="-musl";else echo "Unsupported libc">&2; fi;echo "$arch$libc_postfix"
2019-06-21 02:48:13 +00:00
```
2023-03-05 07:41:15 +00:00
This should give your flavour string. If not this just means that we don't build releases for your platform, you can still try installing from source.
2019-06-21 02:48:13 +00:00
### Installing the required packages
Other than things bundled in the OTP release Pleroma depends on:
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
* curl (to download the release build)
* unzip (needed to unpack release builds)
* ncurses (ERTS won't run without it)
* PostgreSQL (also utilizes extensions in postgresql-contrib)
2019-06-21 16:59:56 +00:00
* nginx (could be swapped with another reverse proxy but this guide covers only it)
2019-06-21 02:48:13 +00:00
* certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
2020-05-14 19:36:31 +00:00
* libmagic/file
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
2021-06-11 06:46:38 +00:00
awk 'NR==2' /etc/apk/repositories | sed 's/main/community/' | tee -a /etc/apk/repositories
2020-08-15 06:49:12 +00:00
apk update
2020-09-10 21:02:11 +00:00
apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot file-dev
2020-08-15 06:49:12 +00:00
```
=== "Debian/Ubuntu"
```
2020-09-10 21:02:11 +00:00
apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2020-09-26 16:32:16 +00:00
### Installing optional packages
2020-10-25 08:28:17 +00:00
Per [`docs/installation/optional/media_graphics_packages.md` ](optional/media_graphics_packages.md ):
2020-09-26 16:32:16 +00:00
* ImageMagick
* ffmpeg
* exiftool
=== "Alpine"
```
apk update
apk add imagemagick ffmpeg exiftool
```
=== "Debian/Ubuntu"
```
apt install imagemagick ffmpeg libimage-exiftool-perl
2020-08-15 06:49:12 +00:00
```
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
## Setup
### Configuring PostgreSQL
#### (Optional) Installing RUM indexes
2019-11-11 12:13:07 +00:00
!!! warning
It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
2019-10-02 21:22:14 +00:00
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).
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "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
```
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
#### (Optional) Performance configuration
2020-05-25 17:26:07 +00:00
It is encouraged to check [Optimizing your PostgreSQL performance ](../configuration/postgresql.md ) document, for tips on PostgreSQL tuning.
2019-06-21 02:48:13 +00:00
2021-01-19 11:15:55 +00:00
Restart PostgreSQL to apply configuration changes:
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
rc-service postgresql restart
```
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
systemctl restart postgresql
```
2019-12-09 17:09:47 +00:00
2019-06-21 02:48:13 +00:00
### Installing Pleroma
```sh
2019-12-09 17:09:47 +00:00
# Create a Pleroma user
2019-06-21 03:32:34 +00:00
adduser --system --shell /bin/false --home /opt/pleroma pleroma
2019-06-21 02:48:13 +00:00
2019-11-11 12:13:07 +00:00
# Set the flavour environment variable to the string you got in Detecting flavour section.
2019-12-09 17:09:47 +00:00
# For example if the flavour is `amd64-musl` the command will be
export FLAVOUR="amd64-musl"
2019-06-21 02:48:13 +00:00
# Clone the release build into a temporary directory and unpack it
su pleroma -s $SHELL -lc "
2019-10-14 15:38:51 +00:00
curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip
2019-06-21 02:48:13 +00:00
unzip /tmp/pleroma.zip -d /tmp/
"
# Move the release to the home directory and delete temporary files
su pleroma -s $SHELL -lc "
mv /tmp/release/* /opt/pleroma
rmdir /tmp/release
rm /tmp/pleroma.zip
"
# Create uploads directory and set proper permissions (skip if planning to use a remote uploader)
# Note: It does not have to be `/var/lib/pleroma/uploads`, the config generator will ask about the upload directory later
mkdir -p /var/lib/pleroma/uploads
2019-06-21 03:39:03 +00:00
chown -R pleroma /var/lib/pleroma
2019-06-21 02:48:13 +00:00
# Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)
# Note: It does not have to be `/var/lib/pleroma/static`, the config generator will ask about the custom public files directory later
mkdir -p /var/lib/pleroma/static
2019-06-21 03:39:03 +00:00
chown -R pleroma /var/lib/pleroma
2019-06-21 02:48:13 +00:00
# Create a config directory
mkdir -p /etc/pleroma
2019-06-21 03:39:03 +00:00
chown -R pleroma /etc/pleroma
2019-06-21 02:48:13 +00:00
# Run the config generator
su pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql"
# Create the postgres database
2019-06-21 23:09:45 +00:00
su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
2019-06-21 02:48:13 +00:00
# Create the database schema
2019-06-21 23:20:55 +00:00
su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
2019-06-21 02:48:13 +00:00
2019-06-21 23:20:55 +00:00
# If you have installed RUM indexes uncommend and run
# su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/"
2019-06-21 03:22:34 +00:00
2019-06-21 02:48:13 +00:00
# Start the instance to verify that everything is working as expected
2021-02-26 01:01:29 +00:00
su pleroma -s $SHELL -lc "./bin/pleroma daemon"
2019-06-21 02:48:13 +00:00
# Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
sleep 20 & & curl http://localhost:4000/api/v1/instance
# Stop the instance
2019-06-21 23:20:55 +00:00
su pleroma -s $SHELL -lc "./bin/pleroma stop"
2019-06-21 02:48:13 +00:00
```
### Setting up nginx and getting Let's Encrypt SSL certificaties
2019-12-09 17:09:47 +00:00
#### Get a Let's Encrypt certificate
2019-06-21 02:48:13 +00:00
```sh
certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
2019-12-09 17:09:47 +00:00
```
#### Copy Pleroma nginx configuration to the nginx folder
2019-06-21 02:48:13 +00:00
2019-12-09 17:09:47 +00:00
The location of nginx configs is dependent on the distro
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
```
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
=== "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
```
2019-12-09 17:09:47 +00:00
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
2019-06-21 02:48:13 +00:00
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
2019-12-09 17:09:47 +00:00
```
2019-06-21 02:48:13 +00:00
2019-12-09 17:09:47 +00:00
#### Edit the nginx config
```sh
# Replace example.tld with your (sub)domain
2019-06-22 10:40:37 +00:00
$EDITOR path-to-nginx-config
2019-06-21 02:48:13 +00:00
# Verify that the config is valid
nginx -t
2019-12-09 17:09:47 +00:00
```
2023-05-26 21:27:35 +00:00
#### (Strongly recommended) serve media on another domain
Refer to the [Hardening your instance ](../configuration/hardening.md ) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
2019-12-09 17:09:47 +00:00
#### Start nginx
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
rc-service nginx start
```
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
systemctl start nginx
```
2019-12-09 17:09:47 +00:00
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.
2019-06-21 02:48:13 +00:00
### Setting up a system service
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
# Copy the service into a proper directory
cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
# Start pleroma and enable it on boot
rc-service pleroma start
rc-update add pleroma
```
2019-06-21 02:48:13 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
# Copy the service into a proper directory
cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# Start pleroma and enable it on boot
systemctl start pleroma
systemctl enable pleroma
```
2019-12-09 17:09:47 +00:00
2019-11-11 12:13:07 +00:00
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.
2019-06-21 02:48:13 +00:00
2021-05-26 04:14:45 +00:00
Questions about the installation or didn’ t it work as it should be, ask in [#pleroma:libera.chat ](https://matrix.to/#/#pleroma:libera.chat ) via Matrix or ** #pleroma ** on **libera.chat** via IRC, you can also [file an issue on our Gitlab ](https://git.pleroma.social/pleroma/pleroma-support/issues/new ).
2019-06-21 02:48:13 +00:00
## Post installation
2019-12-09 17:09:47 +00:00
### Setting up auto-renew of the Let's Encrypt certificate
2019-06-22 23:42:47 +00:00
```sh
# Create the directory for webroot challenges
mkdir -p /var/lib/letsencrypt
# Uncomment the webroot method
$EDITOR path-to-nginx-config
# Verify that the config is valid
nginx -t
```
2020-08-15 06:49:12 +00:00
=== "Alpine"
```
# Restart nginx
rc-service nginx restart
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# Start the cron daemon and make it start on boot
rc-service crond start
rc-update add crond
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# 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'
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# 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
2019-06-22 23:42:47 +00:00
2020-08-15 06:49:12 +00:00
# If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
run-parts --test /etc/periodic/daily
```
2019-06-23 00:05:02 +00:00
2020-08-15 06:49:12 +00:00
=== "Debian/Ubuntu"
```
# Restart nginx
systemctl restart nginx
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# 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'
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# 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
2019-12-09 17:09:47 +00:00
2020-08-15 06:49:12 +00:00
# If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
run-parts --test /etc/cron.daily
```
2019-07-17 22:35:16 +00:00
## Create your first user and set as admin
```sh
2021-04-20 17:31:14 +00:00
cd /opt/pleroma
2019-07-17 22:35:16 +00:00
su pleroma -s $SHELL -lc "./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin"
```
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.
2019-06-23 04:43:45 +00:00
## Further reading
2019-10-02 21:18:32 +00:00
2020-06-22 09:41:22 +00:00
{! backend/installation/further_reading.include !}
2020-01-15 08:12:24 +00:00
## Questions
2021-05-26 04:14:45 +00:00
Questions about the installation or didn’ t it work as it should be, ask in [#pleroma:libera.chat ](https://matrix.to/#/#pleroma:libera.chat ) via Matrix or ** #pleroma ** on **libera.chat** via IRC, you can also [file an issue on our Gitlab ](https://git.pleroma.social/pleroma/pleroma-support/issues/new ).