[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 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 vim /etc/nginx/sites-available/peertube # Comment ssl_certificate and ssl_certificate_key lines
$ sudo certbot --authenticator standalone --installer nginx --post-hook "systemctl start nginx"
$ sudo vim /etc/nginx/sites-available/peertube # Uncomment ssl_certificate and ssl_certificate_key lines
$ 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/
```

Update the service file:

```
$ 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 you instance to the public PeerTube instances index if you want to: https://instances.peertu.be/
 * 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 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 vim /etc/nginx/sites-available/peertube # Comment ssl_certificate and ssl_certificate_key lines
	124	$ sudo certbot --authenticator standalone --installer nginx --post-hook "systemctl start nginx"
	125	$ sudo vim /etc/nginx/sites-available/peertube # Uncomment ssl_certificate and ssl_certificate_key lines
	126	$ sudo systemctl reload nginx
	127	```
	128
	129	Remember your certificate will expire in 90 days, and thus needs renewal.
	130
	131	Now you have the certificates you can reload nginx:
	132
	133	```
	134	$ sudo systemctl reload nginx
	135	```
	136
	137	FreeBSD
	138	On FreeBSD you can use [Dehydrated](https://dehydrated.io/) `security/dehydrated` for [Let's Encrypt](https://letsencrypt.org/)
	139
	140	```
	141	$ sudo pkg install dehydrated
	142	```
	143
	144	### TCP/IP Tuning
	145
	146	On Linux
	147
	148	```
	149	$ sudo cp /var/www/peertube/peertube-latest/support/sysctl.d/30-peertube-tcp.conf /etc/sysctl.d/
	150	$ sudo sysctl -p /etc/sysctl.d/30-peertube-tcp.conf
	151	```
	152
	153	Your distro may enable this by default, but at least Debian 9 does not, and the default FIFO
	154	scheduler is quite prone to "Buffer Bloat" and extreme latency when dealing with slower client
	155	links as we often encounter in a video server.
	156
	157	### systemd
	158
	159	If your OS uses systemd, copy the configuration template:
	160
	161	```
	162	$ sudo cp /var/www/peertube/peertube-latest/support/systemd/peertube.service /etc/systemd/system/
	163	```
	164
	165	Update the service file:
	166
	167	```
	168	$ sudo vim /etc/systemd/system/peertube.service
	169	```
	170
	171
	172	Tell systemd to reload its config:
	173
	174	```
	175	$ sudo systemctl daemon-reload
	176	```
	177
	178	If you want to start PeerTube on boot:
	179
	180	```
	181	$ sudo systemctl enable peertube
	182	```
	183
	184	Run:
	185
	186	```
	187	$ sudo systemctl start peertube
	188	$ sudo journalctl -feu peertube
	189	```
	190
	191	FreeBSD
	192	On FreeBSD, copy the startup script and update rc.conf:
	193
	194	```
	195	$ sudo install -m 0555 /var/www/peertube/peertube-latest/support/freebsd/peertube /usr/local/etc/rc.d/
	196	$ sudo sysrc peertube_enable="YES"
	197	```
	198
	199	Run:
	200
	201	```
	202	$ sudo service peertube start
	203	```
	204
	205	### OpenRC
	206
	207	If your OS uses OpenRC, copy the service script:
	208
	209	```
	210	$ sudo cp /var/www/peertube/peertube-latest/support/init.d/peertube /etc/init.d/
	211	```
	212
	213	If you want to start PeerTube on boot:
	214
	215	```
	216	$ sudo rc-update add peertube default
	217	```
	218
	219	Run and print last logs:
	220
	221	```
	222	$ sudo /etc/init.d/peertube start
	223	$ tail -f /var/log/peertube/peertube.log
	224	```
	225
	226	### Administrator
	227
	228	The administrator password is automatically generated and can be found in the
	229	logs. You can set another password with:
	230
	231	```
	232	$ cd /var/www/peertube/peertube-latest && NODE_CONFIG_DIR=/var/www/peertube/config NODE_ENV=production npm run reset-password -- -u root
	233	```
	234
	235	Alternatively you can set the environment variable `PT_INITIAL_ROOT_PASSWORD`,
	236	to your own administrator password, although it must be 6 characters or more.
	237
	238	### What now?
	239
	240	Now your instance is up you can:
	241
	242	* Subscribe to the mailing list for PeerTube administrators: https://framalistes.org/sympa/subscribe/peertube-admin
	243	* Add you instance to the public PeerTube instances index if you want to: https://instances.peertu.be/
	244	* Check [available CLI tools](/support/doc/tools.md)
	245
	246	## Upgrade
	247
	248	### PeerTube instance
	249
	250	Check the changelog (in particular BREAKING CHANGES!): https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
	251
	252	#### Auto (minor versions only)
	253
	254	The password it asks is PeerTube's database user password.
	255
	256	```
	257	$ cd /var/www/peertube/peertube-latest/scripts && sudo -H -u peertube ./upgrade.sh
	258	```
	259
	260	#### Manually
	261
	262	Make a SQL backup
	263
	264	```
	265	$ SQL_BACKUP_PATH="backup/sql-peertube_prod-$(date -Im).bak" && \
	266	cd /var/www/peertube && sudo -u peertube mkdir -p backup && \
	267	sudo -u postgres pg_dump -F c peertube_prod \| sudo -u peertube tee "$SQL_BACKUP_PATH" >/dev/null
	268	```
	269
	270	Fetch the latest tagged version of Peertube:
	271
	272	```
	273	$ 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"
	274	```
	275
	276	Download the new version and unzip it:
	277
	278	```
	279	$ cd /var/www/peertube/versions && \
	280	sudo -u peertube wget -q "https://github.com/Chocobozzz/PeerTube/releases/download/${VERSION}/peertube-${VERSION}.zip" && \
	281	sudo -u peertube unzip -o peertube-${VERSION}.zip && \
	282	sudo -u peertube rm peertube-${VERSION}.zip
	283	```
	284
	285	Install node dependencies:
	286
	287	```
	288	$ cd /var/www/peertube/versions/peertube-${VERSION} && \
	289	sudo -H -u peertube yarn install --production --pure-lockfile
	290	```
	291
	292	Copy new configuration defaults values and update your configuration file:
	293
	294	```
	295	$ sudo -u peertube cp /var/www/peertube/versions/peertube-${VERSION}/config/default.yaml /var/www/peertube/config/default.yaml
	296	$ diff /var/www/peertube/versions/peertube-${VERSION}/config/production.yaml.example /var/www/peertube/config/production.yaml
	297	```
	298
	299	Change the link to point to the latest version:
	300
	301	```
	302	$ cd /var/www/peertube && \
	303	sudo unlink ./peertube-latest && \
	304	sudo -u peertube ln -s versions/peertube-${VERSION} ./peertube-latest
	305	```
	306
	307	### nginx
	308
	309	Check changes in nginx configuration:
	310
	311	```
	312	$ cd /var/www/peertube/versions
	313	$ diff "$(ls --sort=t \| head -2 \| tail -1)/support/nginx/peertube" "$(ls --sort=t \| head -1)/support/nginx/peertube"
	314	```
	315
	316	### systemd
	317
	318	Check changes in systemd configuration:
	319
	320	```
	321	$ cd /var/www/peertube/versions
	322	$ diff "$(ls --sort=t \| head -2 \| tail -1)/support/systemd/peertube.service" "$(ls --sort=t \| head -1)/support/systemd/peertube.service"
	323	```
	324
	325	### Restart PeerTube
	326
	327	If you changed your nginx configuration:
	328
	329	```
	330	$ sudo systemctl reload nginx
	331	```
	332
	333	If you changed your systemd configuration:
	334
	335	```
	336	$ sudo systemctl daemon-reload
	337	```
	338
	339	Restart PeerTube and check the logs:
	340
	341	```
	342	$ sudo systemctl restart peertube && sudo journalctl -fu peertube
	343	```
	344
	345	### Things went wrong?
	346
	347	Change `peertube-latest` destination to the previous version and restore your SQL backup:
	348
	349	```
	350	$ OLD_VERSION="v0.42.42" && SQL_BACKUP_PATH="backup/sql-peertube_prod-2018-01-19T10:18+01:00.bak" && \
	351	cd /var/www/peertube && sudo -u peertube unlink ./peertube-latest && \
	352	sudo -u peertube ln -s "versions/peertube-$OLD_VERSION" peertube-latest && \
	353	sudo -u postgres pg_restore -c -C -d postgres "$SQL_BACKUP_PATH" && \
	354	sudo systemctl restart peertube
	355	```