otp_en.md 10.8 KB
Newer Older
rinpatch's avatar
rinpatch committed
1
2
3
4
5
6
7
8
# Installing on Linux using OTP releases

## Pre-requisites
* 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
* A (sub)domain pointed to the machine

You will be running commands as root. If you aren't root already, please elevate your priviledges by executing `sudo su`/`su`.

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.
rinpatch's avatar
rinpatch committed
10
11
12
13
14

### Detecting flavour

Paste the following into the shell:
```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"
rinpatch's avatar
rinpatch committed
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.
rinpatch's avatar
rinpatch committed
19
20
21
22

### Installing the required packages

Other than things bundled in the OTP release Pleroma depends on:
23

rinpatch's avatar
rinpatch committed
24
25
26
27
* 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)
28
* nginx (could be swapped with another reverse proxy but this guide covers only it)
rinpatch's avatar
rinpatch committed
29
* certbot (for Let's Encrypt certificates, could be swapped with another ACME client, but this guide covers only it)
href's avatar
href committed
30
* libmagic/file
rinpatch's avatar
rinpatch committed
31

rinpatch's avatar
rinpatch committed
32
33
34
35
=== "Alpine"
    ```
    echo "http://nl.alpinelinux.org/alpine/latest-stable/community" >> /etc/apk/repositories
    apk update
36
    apk add curl unzip ncurses postgresql postgresql-contrib nginx certbot file-dev
rinpatch's avatar
rinpatch committed
37
38
39
40
    ```

=== "Debian/Ubuntu"
    ```
41
    apt install curl unzip libncurses5 postgresql postgresql-contrib nginx certbot libmagic-dev
rinpatch's avatar
rinpatch committed
42
    ```
43

44
45
### Installing optional packages

Kana Kana's avatar
Kana Kana committed
46
Per [`docs/installation/optional/media_graphics_packages.md`](optional/media_graphics_packages.md):
47
48
49
50
51
52
53
54
55
56
57
58
59
60
  * 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
rinpatch's avatar
rinpatch committed
61
    ```
62

rinpatch's avatar
rinpatch committed
63
64
65
## Setup
### Configuring PostgreSQL
#### (Optional) Installing RUM indexes
66
67
68
69

!!! warning
    It is recommended to use PostgreSQL v11 or newer. We have seen some minor issues with lower PostgreSQL versions.

rinpatch's avatar
rinpatch committed
70
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).
rinpatch's avatar
rinpatch committed
71

rinpatch's avatar
rinpatch committed
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
=== "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
    ```
88

rinpatch's avatar
rinpatch committed
89
#### (Optional) Performance configuration
lain's avatar
lain committed
90
It is encouraged to check [Optimizing your PostgreSQL performance](../configuration/postgresql.md) document, for tips on PostgreSQL tuning.
rinpatch's avatar
rinpatch committed
91

92
93
Restart PostgreSQL to apply configuration changes:

rinpatch's avatar
rinpatch committed
94
95
96
97
=== "Alpine"
    ```
    rc-service postgresql restart
    ```
98

rinpatch's avatar
rinpatch committed
99
100
101
102
=== "Debian/Ubuntu"
    ```
    systemctl restart postgresql
    ```
103

rinpatch's avatar
rinpatch committed
104
105
### Installing Pleroma
```sh
106
# Create a Pleroma user
107
adduser --system --shell  /bin/false --home /opt/pleroma pleroma
rinpatch's avatar
rinpatch committed
108

109
# Set the flavour environment variable to the string you got in Detecting flavour section.
110
111
# For example if the flavour is `amd64-musl` the command will be
export FLAVOUR="amd64-musl"
rinpatch's avatar
rinpatch committed
112
113
114

# Clone the release build into a temporary directory and unpack it
su pleroma -s $SHELL -lc "
115
curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip
rinpatch's avatar
rinpatch committed
116
117
118
119
120
121
122
123
124
125
126
127
128
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
129
chown -R pleroma /var/lib/pleroma
rinpatch's avatar
rinpatch committed
130
131
132
133

# 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
134
chown -R pleroma /var/lib/pleroma
rinpatch's avatar
rinpatch committed
135
136
137

# Create a config directory
mkdir -p /etc/pleroma
138
chown -R pleroma /etc/pleroma
rinpatch's avatar
rinpatch committed
139
140
141
142
143

# 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
rinpatch's avatar
rinpatch committed
144
su postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
rinpatch's avatar
rinpatch committed
145
146

# Create the database schema
147
su pleroma -s $SHELL -lc "./bin/pleroma_ctl migrate"
rinpatch's avatar
rinpatch committed
148

149
150
# 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/"
rinpatch's avatar
rinpatch committed
151

rinpatch's avatar
rinpatch committed
152
# Start the instance to verify that everything is working as expected
Maksim's avatar
Maksim committed
153
su pleroma -s $SHELL -lc "export $(cat /opt/pleroma/config/pleroma.env); ./bin/pleroma daemon"
rinpatch's avatar
rinpatch committed
154
155
156
157
158

# 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
159
su pleroma -s $SHELL -lc "./bin/pleroma stop"
rinpatch's avatar
rinpatch committed
160
161
162
163
```

### Setting up nginx and getting Let's Encrypt SSL certificaties

164
#### Get a Let's Encrypt certificate
rinpatch's avatar
rinpatch committed
165
166
```sh
certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
167
168
169
```

#### Copy Pleroma nginx configuration to the nginx folder
rinpatch's avatar
rinpatch committed
170

171
The location of nginx configs is dependent on the distro
rinpatch's avatar
rinpatch committed
172

rinpatch's avatar
rinpatch committed
173
174
175
176
=== "Alpine"
    ```
    cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/conf.d/pleroma.conf
    ```
177

rinpatch's avatar
rinpatch committed
178
179
180
181
182
=== "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
    ```
183
184
185

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
rinpatch's avatar
rinpatch committed
186
cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/pleroma.conf
187
```
rinpatch's avatar
rinpatch committed
188

189
190
191
#### Edit the nginx config
```sh
# Replace example.tld with your (sub)domain
192
$EDITOR path-to-nginx-config
rinpatch's avatar
rinpatch committed
193
194
195

# Verify that the config is valid
nginx -t
196
197
```
#### Start nginx
rinpatch's avatar
rinpatch committed
198

rinpatch's avatar
rinpatch committed
199
200
201
202
=== "Alpine"
    ```
    rc-service nginx start
    ```
rinpatch's avatar
rinpatch committed
203

rinpatch's avatar
rinpatch committed
204
205
206
207
=== "Debian/Ubuntu"
    ```
    systemctl start nginx
    ```
208
209

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.
rinpatch's avatar
rinpatch committed
210
211
212

### Setting up a system service

rinpatch's avatar
rinpatch committed
213
214
215
216
=== "Alpine"
    ```
    # Copy the service into a proper directory
    cp /opt/pleroma/installation/init.d/pleroma /etc/init.d/pleroma
rinpatch's avatar
rinpatch committed
217

rinpatch's avatar
rinpatch committed
218
219
220
221
    # Start pleroma and enable it on boot
    rc-service pleroma start
    rc-update add pleroma
    ```
rinpatch's avatar
rinpatch committed
222

rinpatch's avatar
rinpatch committed
223
224
225
226
=== "Debian/Ubuntu"
    ```
    # Copy the service into a proper directory
    cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
227

rinpatch's avatar
rinpatch committed
228
229
230
231
    # Start pleroma and enable it on boot
    systemctl start pleroma
    systemctl enable pleroma
    ```
232

233
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.
rinpatch's avatar
rinpatch committed
234

235
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)
rinpatch's avatar
rinpatch committed
236
237
238

## Post installation

239
### Setting up auto-renew of the Let's Encrypt certificate
240
241
242
243
244
245
246
247
248
249
250
```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
```

rinpatch's avatar
rinpatch committed
251
252
253
254
=== "Alpine"
    ```
    # Restart nginx
    rc-service nginx restart
255

rinpatch's avatar
rinpatch committed
256
257
258
    # Start the cron daemon and make it start on boot
    rc-service crond start
    rc-update add crond
259

rinpatch's avatar
rinpatch committed
260
261
    # 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'
262

rinpatch's avatar
rinpatch committed
263
264
265
266
267
    # 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
268

rinpatch's avatar
rinpatch committed
269
270
271
    # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
    run-parts --test /etc/periodic/daily
    ```
272

rinpatch's avatar
rinpatch committed
273
274
275
276
=== "Debian/Ubuntu"
    ```
    # Restart nginx
    systemctl restart nginx
277

rinpatch's avatar
rinpatch committed
278
279
    # 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'
280

rinpatch's avatar
rinpatch committed
281
282
283
284
285
    # 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
286

rinpatch's avatar
rinpatch committed
287
288
289
    # If everything worked the output should contain /etc/cron.daily/renew-pleroma-cert
    run-parts --test /etc/cron.daily
    ```
290
291
292
293
294
295
296
297

## Create your first user and set as admin
```sh
cd /opt/pleroma/bin
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.

298
## Further reading
rinpatch's avatar
rinpatch committed
299

300
{! backend/installation/further_reading.include !}
ilja's avatar
ilja committed
301
302
303
304

## 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**.