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