[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/${WEBSERVER_HOST}/[peertube-domain]/g' /etc/nginx/sites-available/peertube
$ sudo sed -i 's/${PEERTUBE_HOST}/localhost:9000/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

A 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.

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