git.squeep.com Git - akkoma/blob - docs/installation/otp_en.md

   1 # Installing on Linux using OTP releases
   2
   3 ## Pre-requisites
   4 * A machine running Linux with GNU (e.g. Debian, Ubuntu) or musl (e.g. Alpine) libc and `x86_64`, `aarch64` or `armv7l` CPU, you have root access to. If you are not sure if it's compatible see [Detecting flavour section](#detecting-flavour) below
   5 * A (sub)domain pointed to the machine
   6
   7 You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`.
   8
   9 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.
  10
  11 ### Detecting flavour
  12
  13 Paste the following into the shell:
  14 ```sh
  15 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"
  16 ```
  17
  18 If your platform is supported the output will contain the flavour string, you will need it later. If not, this just means that we don't build releases for your platform, you can still try installing from source.
  19
  20 ### Installing the required packages
  21
  22 Other than things bundled in the OTP release Pleroma depends on:
  23
  24 * curl (to download the release build)
  25 * unzip (needed to unpack release builds)
  26 * ncurses (ERTS won't run without it)
  27 * PostgreSQL (also utilizes extensions in postgresql-contrib)
  28 * nginx (could be swapped with another reverse proxy but this guide covers only it)
  29 * certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
  30 * libmagic/file
  31
  32 === "Alpine"
  33     ```
  34     echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
  35     apk update
  36     apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot file-dev
  37     ```
  38
  39 === "Debian/Ubuntu"
  40     ```
  41     apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev
  42     ```
  43
  44 ## Setup
  45 ### Configuring PostgreSQL
  46 #### (Optional) Installing RUM indexes
  47
  48 !!! warning
  49     It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.
  50
  51 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).
  52
  53 === "Alpine"
  54     ```
  55     apk add git build-base postgresql-dev
  56     git clone https://github.com/postgrespro/rum /tmp/rum
  57     cd /tmp/rum
  58     make USE_PGXS=1
  59     make USE_PGXS=1 install
  60     cd
  61     rm -r /tmp/rum
  62     ```
  63
  64 === "Debian/Ubuntu"
  65     ```
  66     # Available only on Buster/19.04
  67     apt install postgresql-11-rum
  68     ```
  69
  70 #### (Optional) Performance configuration
  71 It is encouraged to check [Optimizing your PostgreSQL performance](../configuration/postgresql.md) document, for tips on PostgreSQL tuning.
  72
  73 === "Alpine"
  74     ```
  75     rc-service postgresql restart
  76     ```
  77
  78 === "Debian/Ubuntu"
  79     ```
  80     systemctl restart postgresql
  81     ```
  82
  83 If you are using PostgreSQL 12 or higher, add this to your Ecto database configuration
  84
  85 ```elixir
  86 prepare: :named,
  87 parameters: [
  88   plan_cache_mode: "force_custom_plan"
  89 ]
  90 ```
  91
  92 ### Installing Pleroma
  93 ```sh
  94 # Create a Pleroma user
  95 adduser --system --shell  /bin/false --home /opt/pleroma pleroma
  96
  97 # Set the flavour environment variable to the string you got in Detecting flavour section.
  98 # For example if the flavour is `amd64-musl` the command will be
  99 export FLAVOUR="amd64-musl"
 100
 101 # Clone the release build into a temporary directory and unpack it
 102 su pleroma -s $SHELL -lc "
 103 curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip
 104 unzip /tmp/pleroma.zip -d /tmp/
 105 "
 106
 107 # Move the release to the home directory and delete temporary files
 108 su pleroma -s $SHELL -lc "
 109 mv /tmp/release/* /opt/pleroma
 110 rmdir /tmp/release
 111 rm /tmp/pleroma.zip
 112 "
 113 # Create uploads directory and set proper permissions (skip if planning to use a remote uploader)
 114 # Note: It does not have to be `/var/lib/pleroma/uploads`, the config generator will ask about the upload directory later
 115
 116 mkdir -p /var/lib/pleroma/uploads
 117 chown -R pleroma /var/lib/pleroma
 118
 119 # Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)
 120 # Note: It does not have to be `/var/lib/pleroma/static`, the config generator will ask about the custom public files directory later
 121 mkdir -p /var/lib/pleroma/static
 122 chown -R pleroma /var/lib/pleroma
 123
 124 # Create a config directory
 125 mkdir -p /etc/pleroma
 126 chown -R pleroma /etc/pleroma
 127
 128 # Run the config generator
 129 su pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql"
 130
 131 # Create the postgres database
 132 su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
 133
 134 # Create the database schema
 135 su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
 136
 137 # If you have installed RUM indexes uncommend and run
 138 # su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/"
 139
 140 # Start the instance to verify that everything is working as expected
 141 su pleroma -s $SHELL -lc "./bin/pleroma daemon"
 142
 143 # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
 144 sleep 20 && curl http://localhost:4000/api/v1/instance
 145
 146 # Stop the instance
 147 su pleroma -s $SHELL -lc "./bin/pleroma stop"
 148 ```
 149
 150 ### Setting up nginx and getting Let's Encrypt SSL certificaties
 151
 152 #### Get a Let's Encrypt certificate
 153 ```sh
 154 certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
 155 ```
 156
 157 #### Copy Pleroma nginx configuration to the nginx folder
 158
 159 The location of nginx configs is dependent on the distro
 160
 161 === "Alpine"
 162     ```
 163     cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
 164     ```
 165
 166 === "Debian/Ubuntu"
 167     ```
 168     cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf
 169     ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/pleroma.conf
 170     ```
 171
 172 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
 173 ```sh
 174 cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
 175 ```
 176
 177 #### Edit the nginx config
 178 ```sh
 179 # Replace example.tld with your (sub)domain
 180 $EDITOR path-to-nginx-config
 181
 182 # Verify that the config is valid
 183 nginx -t
 184 ```
 185 #### Start nginx
 186
 187 === "Alpine"
 188     ```
 189     rc-service nginx start
 190     ```
 191
 192 === "Debian/Ubuntu"
 193     ```
 194     systemctl start nginx
 195     ```
 196
 197 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.
 198
 199 ### Setting up a system service
 200
 201 === "Alpine"
 202     ```
 203     # Copy the service into a proper directory
 204     cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
 205
 206     # Start pleroma and enable it on boot
 207     rc-service pleroma start
 208     rc-update add pleroma
 209     ```
 210
 211 === "Debian/Ubuntu"
 212     ```
 213     # Copy the service into a proper directory
 214     cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
 215
 216     # Start pleroma and enable it on boot
 217     systemctl start pleroma
 218     systemctl enable pleroma
 219     ```
 220
 221 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.
 222
 223 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)
 224
 225 ## Post installation
 226
 227 ### Setting up auto-renew of the Let's Encrypt certificate
 228 ```sh
 229 # Create the directory for webroot challenges
 230 mkdir -p /var/lib/letsencrypt
 231
 232 # Uncomment the webroot method
 233 $EDITOR path-to-nginx-config
 234
 235 # Verify that the config is valid
 236 nginx -t
 237 ```
 238
 239 === "Alpine"
 240     ```
 241     # Restart nginx
 242     rc-service nginx restart
 243
 244     # Start the cron daemon and make it start on boot
 245     rc-service crond start
 246     rc-update add crond
 247
 248     # Ensure the webroot menthod and post hook is working
 249     certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'rc-service nginx reload'
 250
 251     # Add it to the daily cron
 252     echo '#!/bin/sh
 253     certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "rc-service nginx reload"
 254     ' > /etc/periodic/daily/renew-pleroma-cert
 255     chmod +x /etc/periodic/daily/renew-pleroma-cert
 256
 257     # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
 258     run-parts --test /etc/periodic/daily
 259     ```
 260
 261 === "Debian/Ubuntu"
 262     ```
 263     # Restart nginx
 264     systemctl restart nginx
 265
 266     # Ensure the webroot menthod and post hook is working
 267     certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl reload nginx'
 268
 269     # Add it to the daily cron
 270     echo '#!/bin/sh
 271     certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
 272     ' > /etc/cron.daily/renew-pleroma-cert
 273     chmod +x /etc/cron.daily/renew-pleroma-cert
 274
 275     # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
 276     run-parts --test /etc/cron.daily
 277     ```
 278
 279 ## Create your first user and set as admin
 280 ```sh
 281 cd /opt/pleroma/bin
 282 su pleroma -s $SHELL -lc "./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin"
 283 ```
 284 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.
 285
 286 ## Further reading
 287
 288 {! backend/installation/further_reading.include !}
 289
 290 ## Questions
 291
 292 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**.
 293