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/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 * curl (to download the release build)
  24 * unzip (needed to unpack release builds)
  25 * ncurses (ERTS won't run without it)
  26 * PostgreSQL (also utilizes extensions in postgresql-contrib)
  27 * nginx (could be swapped with another reverse proxy but this guide covers only it)
  28 * certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
  29
  30 Debian/Ubuntu:
  31 ```sh
  32 apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot
  33 ```
  34 Alpine:
  35
  36 ```sh
  37 echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
  38 apk update
  39 apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot
  40 ```
  41
  42 ## Setup
  43 ### Configuring PostgreSQL
  44 #### (Optional) Installing RUM indexes
  45 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).
  46
  47 Debian/Ubuntu (available only on Buster/19.04):
  48 ```sh
  49 apt install postgresql-11-rum
  50 ```
  51 Alpine:
  52 ```sh
  53 apk add git build-base postgresql-dev
  54 git clone https://github.com/postgrespro/rum /tmp/rum
  55 cd /tmp/rum
  56 make USE_PGXS=1
  57 make USE_PGXS=1 install
  58 cd
  59 rm -r /tmp/rum
  60 ```
  61 #### (Optional) Performance configuration
  62 For optimal performance, you may use [PGTune](https://pgtune.leopard.in.ua), don't forget to restart postgresql after editing the configuration
  63
  64 Debian/Ubuntu:
  65 ```sh
  66 systemctl restart postgresql
  67 ```
  68 Alpine:
  69 ```sh
  70 rc-service postgresql restart
  71 ```
  72 ### Installing Pleroma
  73 ```sh
  74 # Create the Pleroma user
  75 adduser --system --shell  /bin/false --home /opt/pleroma pleroma
  76
  77 # Set the flavour environment variable to the string you got in Detecting flavour section.
  78 # For example if the flavour is `arm64-musl` the command will be
  79 export FLAVOUR="arm64-musl"
  80
  81 # Clone the release build into a temporary directory and unpack it
  82 su pleroma -s $SHELL -lc "
  83 curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip
  84 unzip /tmp/pleroma.zip -d /tmp/
  85 "
  86
  87 # Move the release to the home directory and delete temporary files
  88 su pleroma -s $SHELL -lc "
  89 mv /tmp/release/* /opt/pleroma
  90 rmdir /tmp/release
  91 rm /tmp/pleroma.zip
  92 "
  93 # Create uploads directory and set proper permissions (skip if planning to use a remote uploader)
  94 # Note: It does not have to be `/var/lib/pleroma/uploads`, the config generator will ask about the upload directory later
  95
  96 mkdir -p /var/lib/pleroma/uploads
  97 chown -R pleroma /var/lib/pleroma
  98
  99 # Create custom public files directory (custom emojis, frontend bundle overrides, robots.txt, etc.)
 100 # Note: It does not have to be `/var/lib/pleroma/static`, the config generator will ask about the custom public files directory later
 101 mkdir -p /var/lib/pleroma/static
 102 chown -R pleroma /var/lib/pleroma
 103
 104 # Create a config directory
 105 mkdir -p /etc/pleroma
 106 chown -R pleroma /etc/pleroma
 107
 108 # Run the config generator
 109 su pleroma -s $SHELL -lc "./bin/pleroma_ctl instance gen --output /etc/pleroma/config.exs --output-psql /tmp/setup_db.psql"
 110
 111 # Create the postgres database
 112 su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
 113
 114 # Create the database schema
 115 su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
 116
 117 # If you have installed RUM indexes uncommend and run
 118 # su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate --migrations-path priv/repo/optional_migrations/rum_indexing/"
 119
 120 # Start the instance to verify that everything is working as expected
 121 su pleroma -s $SHELL -lc "./bin/pleroma daemon"
 122
 123 # Wait for about 20 seconds and query the instance endpoint, if it shows your uri, name and email correctly, you are configured correctly
 124 sleep 20 && curl http://localhost:4000/api/v1/instance
 125
 126 # Stop the instance
 127 su pleroma -s $SHELL -lc "./bin/pleroma stop"
 128 ```
 129
 130 ### Setting up nginx and getting Let's Encrypt SSL certificaties
 131
 132 ```sh
 133 # Get a Let's Encrypt certificate
 134 certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
 135
 136 # Copy the Pleroma nginx configuration to the nginx folder
 137 # The location of nginx configs is dependent on the distro
 138
 139 # For Debian/Ubuntu:
 140 cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.nginx
 141 ln -s /etc/nginx/sites-available/pleroma.nginx /etc/nginx/sites-enabled/pleroma.nginx
 142 # For Alpine:
 143 cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
 144 # If your distro does not have either of those you can append
 145 # `include /etc/nginx/pleroma.conf` to the end of the http section in /etc/nginx/nginx.conf and
 146 cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
 147
 148 # Edit the nginx config replacing example.tld with your (sub)domain
 149 $EDITOR path-to-nginx-config
 150
 151 # Verify that the config is valid
 152 nginx -t
 153
 154 # Start nginx
 155 # For Debian/Ubuntu:
 156 systemctl start nginx
 157 # For Alpine:
 158 rc-service nginx start
 159 ```
 160
 161 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.
 162
 163 ### Setting up a system service
 164 Debian/Ubuntu:
 165 ```sh
 166 # Copy the service into a proper directory
 167 cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
 168
 169 # Start pleroma and enable it on boot
 170 systemctl start pleroma
 171 systemctl enable pleroma
 172 ```
 173 Alpine:
 174 ```sh
 175 # Copy the service into a proper directory
 176 cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
 177
 178 # Start pleroma and enable it on boot
 179 rc-service pleroma start
 180 rc-update add pleroma
 181 ```
 182
 183 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.
 184
 185 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)
 186
 187 ## Post installation
 188
 189 ### Setting up auto-renew Let's Encrypt certificate
 190 ```sh
 191 # Create the directory for webroot challenges
 192 mkdir -p /var/lib/letsencrypt
 193
 194 # Uncomment the webroot method
 195 $EDITOR path-to-nginx-config
 196
 197 # Verify that the config is valid
 198 nginx -t
 199 ```
 200 Debian/Ubuntu:
 201 ```sh
 202 # Restart nginx
 203 systemctl restart nginx
 204
 205 # Ensure the webroot menthod and post hook is working
 206 certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'systemctl nginx reload'
 207
 208 # Add it to the daily cron
 209 echo '#!/bin/sh
 210 certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
 211 ' > /etc/cron.daily/renew-pleroma-cert
 212 chmod +x /etc/cron.daily/renew-pleroma-cert
 213
 214 # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
 215 run-parts --test /etc/cron.daily
 216 ```
 217 Alpine:
 218 ```sh
 219 # Restart nginx
 220 rc-service nginx restart
 221
 222 # Start the cron daemon and make it start on boot
 223 rc-service crond start
 224 rc-update add crond
 225
 226 # Ensure the webroot menthod and post hook is working
 227 certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --dry-run --post-hook 'rc-service nginx reload'
 228
 229 # Add it to the daily cron
 230 echo '#!/bin/sh
 231 certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "rc-service nginx reload"
 232 ' > /etc/periodic/daily/renew-pleroma-cert
 233 chmod +x /etc/periodic/daily/renew-pleroma-cert
 234
 235 # If everything worked this should output /etc/periodic/daily/renew-pleroma-cert
 236 run-parts --test /etc/periodic/daily
 237 ```
 238 ### Running mix tasks
 239 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.
 240
 241 So for example, if the task is `mix pleroma.user set admin --admin`, you should run it like this:
 242 ```sh
 243 su pleroma -s $SHELL -lc "./bin/pleroma_ctl user set admin --admin"
 244 ```
 245
 246 ## Create your first user and set as admin
 247 ```sh
 248 cd /opt/pleroma/bin
 249 su pleroma -s $SHELL -lc "./bin/pleroma_ctl user new joeuser joeuser@sld.tld --admin"
 250 ```
 251 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.
 252
 253 ### Updating
 254 Generally, doing the following is enough:
 255 ```sh
 256 # Download the new release
 257 su pleroma -s $SHELL -lc "./bin/pleroma_ctl update"
 258
 259 # Migrate the database, you are advised to stop the instance before doing that
 260 su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
 261 ```
 262 But you should **always check the release notes/changelog** in case there are config deprecations, special update steps, etc.
 263
 264 ## Further reading
 265
 266 * [Backup your instance](../administration/backup.md)
 267 * [Hardening your instance](../configuration/hardening.md)
 268 * [How to activate mediaproxy](../configuration/howto_mediaproxy.md)
 269 * [Updating your instance](../administration/updating.md)