]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blame_incremental - support/doc/production.md
fix nginx units
[github/Chocobozzz/PeerTube.git] / support / doc / production.md
... / ...
CommitLineData
1# Production guide
2
3 * [Installation](#installation)
4 * [Upgrade](#upgrade)
5
6## Installation
7
8Please don't install PeerTube for production on a device behind a low bandwidth connection (example: your ADSL link).
9If you want information about the appropriate hardware to run PeerTube, please see the [FAQ](https://github.com/Chocobozzz/PeerTube/blob/develop/FAQ.md#should-i-have-a-big-server-to-run-peertube).
10
11### Dependencies
12
13**Follow the steps of the [dependencies guide](dependencies.md).**
14
15### PeerTube user
16
17Create a `peertube` user with `/var/www/peertube` home:
18
19```
20$ sudo useradd -m -d /var/www/peertube -s /bin/bash -p peertube peertube
21```
22
23Set its password:
24```
25$ sudo passwd peertube
26```
27
28**On FreeBSD**
29
30```
31$ sudo pw useradd -n peertube -d /var/www/peertube -s /usr/local/bin/bash -m
32$ sudo passwd peertube
33```
34or use `adduser` to create it interactively.
35
36### Database
37
38Create the production database and a peertube user inside PostgreSQL:
39
40```
41$ sudo -u postgres createuser -P peertube
42$ sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
43```
44
45Then enable extensions PeerTube needs:
46
47```
48$ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
49$ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod
50```
51
52### Prepare PeerTube directory
53
54Fetch the latest tagged version of Peertube
55```
56$ VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
57```
58
59Open the peertube directory, create a few required directories
60```
61$ cd /var/www/peertube
62$ sudo -u peertube mkdir config storage versions
63```
64
65Download the latest version of the Peertube client, unzip it and remove the zip
66```
67$ cd /var/www/peertube/versions
68$ sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip"
69$ sudo -u peertube unzip peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip
70```
71
72Install Peertube:
73```
74$ cd /var/www/peertube
75$ sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
76$ cd ./peertube-latest && sudo -H -u peertube yarn install --production --pure-lockfile
77```
78
79### PeerTube configuration
80
81Copy the default configuration file that contains the default configuration provided by PeerTube.
82You **must not** update this file.
83
84```
85$ cd /var/www/peertube
86$ sudo -u peertube cp peertube-latest/config/default.yaml config/default.yaml
87```
88
89Now copy the production example configuration:
90
91```
92$ cd /var/www/peertube
93$ sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
94```
95
96Then edit the `config/production.yaml` file according to your webserver
97and database configuration (`webserver`, `database`, `redis`, `smtp` and `admin.email` sections in particular).
98Keys defined in `config/production.yaml` will override keys defined in `config/default.yaml`.
99
100**PeerTube does not support webserver host change**. Even though [PeerTube CLI can help you to switch hostname](https://docs.joinpeertube.org/maintain-tools?id=update-hostjs) there's no official support for that since it is a risky operation that might result in unforeseen errors.
101
102### Webserver
103
104We only provide official configuration files for Nginx.
105
106Copy the nginx configuration template:
107
108```
109$ sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
110```
111
112Then set the domain for the webserver configuration file.
113Replace `[peertube-domain]` with the domain for the peertube server.
114
115```
116$ sudo sed -i 's/${WEBSERVER_HOST}/[peertube-domain]/g' /etc/nginx/sites-available/peertube
117$ sudo sed -i 's/${PEERTUBE_HOST}/127.0.0.1:9000/g' /etc/nginx/sites-available/peertube
118```
119
120Then modify the webserver configuration file. Please pay attention to the `alias` keys of the static locations.
121It should correspond to the paths of your storage directories (set in the configuration file inside the `storage` key).
122
123```
124$ sudo vim /etc/nginx/sites-available/peertube
125```
126
127Activate the configuration file:
128
129```
130$ sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
131```
132
133To generate the certificate for your domain as required to make https work you can use [Let's Encrypt](https://letsencrypt.org/):
134
135```
136$ sudo systemctl stop nginx
137$ sudo certbot certonly --standalone --post-hook "systemctl start nginx"
138$ sudo systemctl reload nginx
139```
140
141Now you have the certificates you can reload nginx:
142
143```
144$ sudo systemctl reload nginx
145```
146
147Certbot should have installed a cron to automatically renew your certificate.
148Since our nginx template supports webroot renewal, we suggest you to update the renewal config file to use the `webroot` authenticator:
149
150```
151$ # Replace authenticator = standalone by authenticator = webroot
152$ sudo vim /etc/letsencrypt/renewal/your-domain.com.conf
153```
154
155**FreeBSD**
156On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)
157
158```
159$ sudo pkg install dehydrated
160```
161
162### TCP/IP Tuning
163
164A lot of your instance's raw performance is dependent on a properly tuned machine and more specifically, reverse-proxy. We provide support for Nginx and spent a lot of time putting sane defaults in it, but we strongly advise you to follow up with instructions in https://github.com/denji/nginx-tuning as needed.
165
166**On Linux**
167
168```
169$ sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
170$ sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
171```
172
173Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
174scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
175links as we often encounter in a video server.
176
177### systemd
178
179If your OS uses systemd, copy the configuration template:
180
181```
182$ sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
183```
184
185Check the service file (PeerTube paths and security directives):
186
187```
188$ sudo vim /etc/systemd/system/peertube.service
189```
190
191
192Tell systemd to reload its config:
193
194```
195$ sudo systemctl daemon-reload
196```
197
198If you want to start PeerTube on boot:
199
200```
201$ sudo systemctl enable peertube
202```
203
204Run:
205
206```
207$ sudo systemctl start peertube
208$ sudo journalctl -feu peertube
209```
210
211**FreeBSD**
212On FreeBSD, copy the startup script and update rc.conf:
213
214```
215$ sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
216$ sudo sysrc peertube_enable="YES"
217```
218
219Run:
220
221```
222$ sudo service peertube start
223```
224
225### OpenRC
226
227If your OS uses OpenRC, copy the service script:
228
229```
230$ sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
231```
232
233If you want to start PeerTube on boot:
234
235```
236$ sudo rc-update add peertube default
237```
238
239Run and print last logs:
240
241```
242$ sudo /etc/init.d/peertube start
243$ tail -f /var/log/peertube/peertube.log
244```
245
246### Administrator
247
248The administrator password is automatically generated and can be found in the PeerTube
249logs (path defined in `production.yaml`). You can also set another password with:
250
251```
252$ cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
253```
254
255Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
256to your own administrator password, although it must be 6 characters or more.
257
258### What now?
259
260Now your instance is up you can:
261
262 * Add your instance to the public PeerTube instances index if you want to: https://instances.joinpeertube.org/
263 * Check [available CLI tools](/support/doc/tools.md)
264
265## Upgrade
266
267### PeerTube instance
268
269**Check the changelog (in particular BREAKING CHANGES!):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
270
271#### Auto
272
273The password it asks is PeerTube's database user password.
274
275```
276$ cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
277```
278
279#### Manually
280
281Make a SQL backup
282
283```
284$ SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
285 cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
286 sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
287```
288
289Fetch the latest tagged version of Peertube:
290
291```
292$ VERSION=$(curl -s https://api.github.com/repos/chocobozzz/peertube/releases/latest | grep tag_name | cut -d '"' -f 4) && echo "Latest Peertube version is $VERSION"
293```
294
295Download the new version and unzip it:
296
297```
298$ cd /var/www/peertube/versions && \
299 sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
300 sudo -u peertube unzip -o peertube-${VERSION}.zip && \
301 sudo -u peertube rm peertube-${VERSION}.zip
302```
303
304Install node dependencies:
305
306```
307$ cd /var/www/peertube/versions/peertube-${VERSION} && \
308 sudo -H -u peertube yarn install --production --pure-lockfile
309```
310
311Copy new configuration defaults values and update your configuration file:
312
313```
314$ sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
315$ diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
316```
317
318Change the link to point to the latest version:
319
320```
321$ cd /var/www/peertube && \
322 sudo unlink ./peertube-latest && \
323 sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
324```
325
326### nginx
327
328Check changes in nginx configuration:
329
330```
331$ cd /var/www/peertube/versions
332$ diff "$(ls --sort=t | head -2 | tail -1)/support/nginx/peertube" "$(ls --sort=t | head -1)/support/nginx/peertube"
333```
334
335### systemd
336
337Check changes in systemd configuration:
338
339```
340$ cd /var/www/peertube/versions
341$ diff "$(ls --sort=t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls --sort=t | head -1)/support/systemd/peertube.service"
342```
343
344### Restart PeerTube
345
346If you changed your nginx configuration:
347
348```
349$ sudo systemctl reload nginx
350```
351
352If you changed your systemd configuration:
353
354```
355$ sudo systemctl daemon-reload
356```
357
358Restart PeerTube and check the logs:
359
360```
361$ sudo systemctl restart peertube && sudo journalctl -fu peertube
362```
363
364### Things went wrong?
365
366Change `peertube-latest` destination to the previous version and restore your SQL backup:
367
368```
369$ OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-2018-01-19T10:18+01:00.bak" && \
370 cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
371 sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
372 sudo -u postgres pg_restore -c -C -d postgres "$SQL_BACKUP_PATH" && \
373 sudo systemctl restart peertube
374```