[github/Chocobozzz/PeerTube.git] / support / doc / production.md

# Production guide

  * [Installation](#installation)
  * [Upgrade](#upgrade)

## Installation

Please don't install PeerTube for production on a device behind a low bandwidth connection (example: your ADSL link).
If 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).

### Dependencies

**Follow the steps of the [dependencies guide](dependencies.md).**

### PeerTube user

Create a `peertube` user with `/var/www/peertube` home:

```
$ sudo useradd -m -d /var/www/peertube -s /bin/bash -p peertube peertube
```

Set its password:
```
$ sudo passwd peertube
```

**On FreeBSD**

```
$ sudo pw useradd -n peertube -d /var/www/peertube -s /usr/local/bin/bash -m
$ sudo passwd peertube
```
or use `adduser` to create it interactively.

### Database

Create the production database and a peertube user inside PostgreSQL:

```
$ sudo -u postgres createuser -P peertube
$ sudo -u postgres createdb -O peertube -E UTF8 -T template0 peertube_prod
```

Then enable extensions PeerTube needs:

```
$ sudo -u postgres psql -c "CREATE EXTENSION pg_trgm;" peertube_prod
$ sudo -u postgres psql -c "CREATE EXTENSION unaccent;" peertube_prod
```

### Prepare PeerTube directory

Fetch the latest tagged version of Peertube
```
$ 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"
```

Open the peertube directory, create a few required directories
```
$ cd /var/www/peertube && sudo -u peertube mkdir config storage versions && cd versions
```

Download the latest version of the Peertube client, unzip it and remove the zip
```
$ sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip"
$ sudo -u peertube unzip peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip
```

Install Peertube:
```
$ cd ../ && sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
$ cd ./peertube-latest && sudo -H -u peertube yarn install --production --pure-lockfile
```

### PeerTube configuration

Copy example configuration:

```
$ cd /var/www/peertube && sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
```

Then edit the `config/production.yaml` file according to your webserver
configuration.

**PeerTube does not support webserver host change**. Keep in mind your domain name is definitive after your first PeerTube start.

### Webserver

We only provide official configuration files for Nginx.

Copy the nginx configuration template:

```
$ sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
```

Then set the domain for the webserver configuration file.
Replace `[peertube-domain]` with the domain for the peertube server.

```
$ sudo sed -i 's/peertube.example.com/[peertube-domain]/g' /etc/nginx/sites-available/peertube
```

Then modify the webserver configuration file. Please pay attention to the `alias` keys of the static locations.
It should correspond to the paths of your storage directories (set in the configuration file inside the `storage` key).

```
$ sudo vim /etc/nginx/sites-available/peertube
```

Activate the configuration file:

```
$ sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
```

To generate the certificate for your domain as required to make https work you can use [Let's Encrypt](https://letsencrypt.org/):

```
$ sudo systemctl stop nginx
$ sudo certbot certonly --standalone --post-hook "systemctl start nginx"
$ sudo systemctl reload nginx
```

Remember your certificate will expire in 90 days, and thus needs renewal.

Now you have the certificates you can reload nginx:

```
$ sudo systemctl reload nginx
```

**FreeBSD**
On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)

```
$ sudo pkg install dehydrated
```

### TCP/IP Tuning

**On Linux**

```
$ sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
$ sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
```

Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
links as we often encounter in a video server.

### systemd

If your OS uses systemd, copy the configuration template:

```
$ sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
```

Check the service file (PeerTube paths and security directives):

```
$ sudo vim /etc/systemd/system/peertube.service
```


Tell systemd to reload its config:

```
$ sudo systemctl daemon-reload
```

If you want to start PeerTube on boot:

```
$ sudo systemctl enable peertube
```

Run:

```
$ sudo systemctl start peertube
$ sudo journalctl -feu peertube
```

**FreeBSD**
On FreeBSD, copy the startup script and update rc.conf:

```
$ sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
$ sudo sysrc peertube_enable="YES"
```

Run:

```
$ sudo service peertube start
```

### OpenRC

If your OS uses OpenRC, copy the service script:

```
$ sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
```

If you want to start PeerTube on boot:

```
$ sudo rc-update add peertube default
```

Run and print last logs:

```
$ sudo /etc/init.d/peertube start
$ tail -f /var/log/peertube/peertube.log
```

### Administrator

The administrator password is automatically generated and can be found in the
logs. You can set another password with:

```
$ cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
```

Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
to your own administrator password, although it must be 6 characters or more.

### What now?

Now your instance is up you can:

 * Subscribe to the mailing list for PeerTube administrators: https://framalistes.org/sympa/subscribe/peertube-admin
 * Add your instance to the public PeerTube instances index if you want to: https://instances.joinpeertube.org/
 * Check [available CLI tools](/support/doc/tools.md)

## Upgrade

### PeerTube instance

**Check the changelog (in particular BREAKING CHANGES!):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md

#### Auto (minor versions only)

The password it asks is PeerTube's database user password.

```
$ cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
```

#### Manually

Make a SQL backup

```
$ SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
    cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
    sudo -u postgres pg_dump -F c peertube_prod | sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
```

Fetch the latest tagged version of Peertube:

```
$ 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"
```

Download the new version and unzip it:

```
$ cd /var/www/peertube/versions && \
    sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
    sudo -u peertube unzip -o peertube-${VERSION}.zip && \
    sudo -u peertube rm peertube-${VERSION}.zip
```

Install node dependencies:

```
$ cd /var/www/peertube/versions/peertube-${VERSION} && \
    sudo -H -u peertube yarn install --production --pure-lockfile
```

Copy new configuration defaults values and update your configuration file:

```
$ sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
$ diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
```

Change the link to point to the latest version:

```
$ cd /var/www/peertube && \
    sudo unlink ./peertube-latest && \
    sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
```

### nginx

Check changes in nginx configuration:

```
$ cd /var/www/peertube/versions
$ diff "$(ls --sort=t | head -2 | tail -1)/support/nginx/peertube" "$(ls --sort=t | head -1)/support/nginx/peertube"
```

### systemd

Check changes in systemd configuration:

```
$ cd /var/www/peertube/versions
$ diff "$(ls --sort=t | head -2 | tail -1)/support/systemd/peertube.service" "$(ls --sort=t | head -1)/support/systemd/peertube.service"
```

### Restart PeerTube

If you changed your nginx configuration:

```
$ sudo systemctl reload nginx
```

If you changed your systemd configuration:

```
$ sudo systemctl daemon-reload
```

Restart PeerTube and check the logs:

```
$ sudo systemctl restart peertube && sudo journalctl -fu peertube
```

### Things went wrong?

Change `peertube-latest` destination to the previous version and restore your SQL backup:

```
$ OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-2018-01-19T10:18+01:00.bak" && \
    cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
    sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
    sudo -u postgres pg_restore -c -C -d postgres "$SQL_BACKUP_PATH" && \
    sudo systemctl restart peertube
```
Commit	Line	Data
	1	# Production guide
	2
	3	* [Installation](#installation)
	4	* [Upgrade](#upgrade)
	5
	6	## Installation
	7
	8	Please don't install PeerTube for production on a device behind a low bandwidth connection (example: your ADSL link).
	9	If 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
	17	Create 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
	23	Set 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	```
	34	or use `adduser` to create it interactively.
	35
	36	### Database
	37
	38	Create 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
	45	Then 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
	54	Fetch 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
	59	Open the peertube directory, create a few required directories
	60	```
	61	$ cd /var/www/peertube && sudo -u peertube mkdir config storage versions && cd versions
	62	```
	63
	64	Download the latest version of the Peertube client, unzip it and remove the zip
	65	```
	66	$ sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip"
	67	$ sudo -u peertube unzip peertube-${VERSION}.zip && sudo -u peertube rm peertube-${VERSION}.zip
	68	```
	69
	70	Install Peertube:
	71	```
	72	$ cd ../ && sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
	73	$ cd ./peertube-latest && sudo -H -u peertube yarn install --production --pure-lockfile
	74	```
	75
	76	### PeerTube configuration
	77
	78	Copy example configuration:
	79
	80	```
	81	$ cd /var/www/peertube && sudo -u peertube cp peertube-latest/config/production.yaml.example config/production.yaml
	82	```
	83
	84	Then edit the `config/production.yaml` file according to your webserver
	85	configuration.
	86
	87	PeerTube does not support webserver host change. Keep in mind your domain name is definitive after your first PeerTube start.
	88
	89	### Webserver
	90
	91	We only provide official configuration files for Nginx.
	92
	93	Copy the nginx configuration template:
	94
	95	```
	96	$ sudo cp /var/www/peertube/peertube-latest/support/nginx/peertube /etc/nginx/sites-available/peertube
	97	```
	98
	99	Then set the domain for the webserver configuration file.
	100	Replace `[peertube-domain]` with the domain for the peertube server.
	101
	102	```
	103	$ sudo sed -i 's/peertube.example.com/[peertube-domain]/g' /etc/nginx/sites-available/peertube
	104	```
	105
	106	Then modify the webserver configuration file. Please pay attention to the `alias` keys of the static locations.
	107	It should correspond to the paths of your storage directories (set in the configuration file inside the `storage` key).
	108
	109	```
	110	$ sudo vim /etc/nginx/sites-available/peertube
	111	```
	112
	113	Activate the configuration file:
	114
	115	```
	116	$ sudo ln -s /etc/nginx/sites-available/peertube /etc/nginx/sites-enabled/peertube
	117	```
	118
	119	To generate the certificate for your domain as required to make https work you can use [Let's Encrypt](https://letsencrypt.org/):
	120
	121	```
	122	$ sudo systemctl stop nginx
	123	$ sudo certbot certonly --standalone --post-hook "systemctl start nginx"
	124	$ sudo systemctl reload nginx
	125	```
	126
	127	Remember your certificate will expire in 90 days, and thus needs renewal.
	128
	129	Now you have the certificates you can reload nginx:
	130
	131	```
	132	$ sudo systemctl reload nginx
	133	```
	134
	135	FreeBSD
	136	On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)
	137
	138	```
	139	$ sudo pkg install dehydrated
	140	```
	141
	142	### TCP/IP Tuning
	143
	144	On Linux
	145
	146	```
	147	$ sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
	148	$ sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
	149	```
	150
	151	Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
	152	scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
	153	links as we often encounter in a video server.
	154
	155	### systemd
	156
	157	If your OS uses systemd, copy the configuration template:
	158
	159	```
	160	$ sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
	161	```
	162
	163	Check the service file (PeerTube paths and security directives):
	164
	165	```
	166	$ sudo vim /etc/systemd/system/peertube.service
	167	```
	168
	169
	170	Tell systemd to reload its config:
	171
	172	```
	173	$ sudo systemctl daemon-reload
	174	```
	175
	176	If you want to start PeerTube on boot:
	177
	178	```
	179	$ sudo systemctl enable peertube
	180	```
	181
	182	Run:
	183
	184	```
	185	$ sudo systemctl start peertube
	186	$ sudo journalctl -feu peertube
	187	```
	188
	189	FreeBSD
	190	On FreeBSD, copy the startup script and update rc.conf:
	191
	192	```
	193	$ sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
	194	$ sudo sysrc peertube_enable="YES"
	195	```
	196
	197	Run:
	198
	199	```
	200	$ sudo service peertube start
	201	```
	202
	203	### OpenRC
	204
	205	If your OS uses OpenRC, copy the service script:
	206
	207	```
	208	$ sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
	209	```
	210
	211	If you want to start PeerTube on boot:
	212
	213	```
	214	$ sudo rc-update add peertube default
	215	```
	216
	217	Run and print last logs:
	218
	219	```
	220	$ sudo /etc/init.d/peertube start
	221	$ tail -f /var/log/peertube/peertube.log
	222	```
	223
	224	### Administrator
	225
	226	The administrator password is automatically generated and can be found in the
	227	logs. You can set another password with:
	228
	229	```
	230	$ cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
	231	```
	232
	233	Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
	234	to your own administrator password, although it must be 6 characters or more.
	235
	236	### What now?
	237
	238	Now your instance is up you can:
	239
	240	* Subscribe to the mailing list for PeerTube administrators: https://framalistes.org/sympa/subscribe/peertube-admin
	241	* Add your instance to the public PeerTube instances index if you want to: https://instances.joinpeertube.org/
	242	* Check [available CLI tools](/support/doc/tools.md)
	243
	244	## Upgrade
	245
	246	### PeerTube instance
	247
	248	Check the changelog (in particular BREAKING CHANGES!): https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
	249
	250	#### Auto (minor versions only)
	251
	252	The password it asks is PeerTube's database user password.
	253
	254	```
	255	$ cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
	256	```
	257
	258	#### Manually
	259
	260	Make a SQL backup
	261
	262	```
	263	$ SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
	264	cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
	265	sudo -u postgres pg_dump -F c peertube_prod \| sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
	266	```
	267
	268	Fetch the latest tagged version of Peertube:
	269
	270	```
	271	$ 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"
	272	```
	273
	274	Download the new version and unzip it:
	275
	276	```
	277	$ cd /var/www/peertube/versions && \
	278	sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
	279	sudo -u peertube unzip -o peertube-${VERSION}.zip && \
	280	sudo -u peertube rm peertube-${VERSION}.zip
	281	```
	282
	283	Install node dependencies:
	284
	285	```
	286	$ cd /var/www/peertube/versions/peertube-${VERSION} && \
	287	sudo -H -u peertube yarn install --production --pure-lockfile
	288	```
	289
	290	Copy new configuration defaults values and update your configuration file:
	291
	292	```
	293	$ sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
	294	$ diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
	295	```
	296
	297	Change the link to point to the latest version:
	298
	299	```
	300	$ cd /var/www/peertube && \
	301	sudo unlink ./peertube-latest && \
	302	sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
	303	```
	304
	305	### nginx
	306
	307	Check changes in nginx configuration:
	308
	309	```
	310	$ cd /var/www/peertube/versions
	311	$ diff "$(ls --sort=t \| head -2 \| tail -1)/support/nginx/peertube" "$(ls --sort=t \| head -1)/support/nginx/peertube"
	312	```
	313
	314	### systemd
	315
	316	Check changes in systemd configuration:
	317
	318	```
	319	$ cd /var/www/peertube/versions
	320	$ diff "$(ls --sort=t \| head -2 \| tail -1)/support/systemd/peertube.service" "$(ls --sort=t \| head -1)/support/systemd/peertube.service"
	321	```
	322
	323	### Restart PeerTube
	324
	325	If you changed your nginx configuration:
	326
	327	```
	328	$ sudo systemctl reload nginx
	329	```
	330
	331	If you changed your systemd configuration:
	332
	333	```
	334	$ sudo systemctl daemon-reload
	335	```
	336
	337	Restart PeerTube and check the logs:
	338
	339	```
	340	$ sudo systemctl restart peertube && sudo journalctl -fu peertube
	341	```
	342
	343	### Things went wrong?
	344
	345	Change `peertube-latest` destination to the previous version and restore your SQL backup:
	346
	347	```
	348	$ OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-2018-01-19T10:18+01:00.bak" && \
	349	cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
	350	sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
	351	sudo -u postgres pg_restore -c -C -d postgres "$SQL_BACKUP_PATH" && \
	352	sudo systemctl restart peertube
	353	```