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

# Docker guide

This guide requires [docker](https://www.docker.com/community-edition) and
[docker-compose](https://docs.docker.com/compose/install/).

## Install

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

#### Go to your workdir

_note_: the guide that follows assumes an empty workdir, but you can also clone the repository, use the master branch and `cd support/docker/production`.

```shell
cd /your/peertube/directory
```

#### Get the latest Compose file

```shell
curl https://raw.githubusercontent.com/chocobozzz/PeerTube/master/support/docker/production/docker-compose.yml > docker-compose.yml
```

View the source of the file you're about to download: [docker-compose.yml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/docker-compose.yml)

#### Get the latest env_file

```shell
curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/docker/production/.env > .env
```

View the source of the file you're about to download: [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env)

#### Tweak the `docker-compose.yml` file there according to your needs

```shell
sudo nano docker-compose.yml
```

#### Then tweak the `.env` file to change the environment variables settings

```shell
sudo nano .env
```

In the downloaded example [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env), you must replace:
- `<MY POSTGRES USERNAME>`
- `<MY POSTGRES PASSWORD>`
- `<MY DOMAIN>` without 'https://'
- `<MY EMAIL ADDRESS>`
- `<MY PEERTUBE SECRET>`

Other environment variables are used in
[/support/docker/production/config/custom-environment-variables.yaml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/custom-environment-variables.yaml) and can be
intuited from usage.

#### Webserver

*The docker compose file includes a configured web server. You can skip this part and comment the appropriate section in the docker compose if you use another webserver/proxy.*

Install the template that the nginx container will use.
The container will generate the configuration by replacing `${WEBSERVER_HOST}` and `${PEERTUBE_HOST}` using your docker compose env file.

```shell
mkdir -p docker-volume/nginx
curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/nginx/peertube > docker-volume/nginx/peertube
```

You need to manually generate the first SSL/TLS certificate using Let's Encrypt:

```shell
mkdir -p docker-volume/certbot
docker run -it --rm --name certbot -p 80:80 -v "$(pwd)/docker-volume/certbot/conf:/etc/letsencrypt" certbot/certbot certonly --standalone
```

A dedicated container in the docker-compose will automatically renew this certificate and reload nginx.


#### Test your setup

_note_: Newer versions of compose are called with `docker compose` instead of `docker-compose`, so remove the dash in all steps that use this command if you are getting errors.

Run your containers:

```shell
docker-compose up
```

#### Obtaining your automatically-generated admin credentials

You can change the automatically created password for user root by running this command from peertube's root directory:
```shell
docker-compose exec -u peertube peertube npm run reset-password -- -u root
```

You can also grep your peertube container's logs for the default `root` password. You're going to want to run `docker-compose logs peertube | grep -A1 root` to search the log output for your new PeerTube's instance admin credentials which will look something like this.

```bash
$ docker-compose logs peertube | grep -A1 root

peertube_1  | [example.com:443] 2019-11-16 04:26:06.082 info: Username: root
peertube_1  | [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
```

#### Obtaining Your Automatically Generated DKIM DNS TXT Record

[DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) signature sending and RSA keys generation are enabled by the default Postfix image `mwader/postfix-relay` with [OpenDKIM](http://www.opendkim.org/).

Run `cat ./docker-volume/opendkim/keys/*/*.txt` to display your DKIM DNS TXT Record containing the public key to configure to your domain :

```bash
$ cat ./docker-volume/opendkim/keys/*/*.txt

peertube._domainkey.mydomain.tld.	IN	TXT	( "v=DKIM1; h=sha256; k=rsa; "
	  "p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dx7wLGPFVaxVQ4TGym/eF89aQ8oMxS9v5BCc26Hij91t2Ci8Fl12DHNVqZoIPGm+9tTIoDVDFEFrlPhMOZl8i4jU9pcFjjaIISaV2+qTa8uV1j3MyByogG8pu4o5Ill7zaySYFsYB++cHJ9pjbFSC42dddCYMfuVgrBsLNrvEi3dLDMjJF5l92Uu8YeswFe26PuHX3Avr261n"
	  "j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" )  ; ----- DKIM key peertube for mydomain.tld
```

#### Administrator password

See the production guide ["Administrator" section](https://docs.joinpeertube.org/install/any-os#administrator)

#### What now?

See the production guide ["What now" section](https://docs.joinpeertube.org/install/any-os#what-now).

## Upgrade

**Check the changelog (in particular the *IMPORTANT NOTES* section):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md

Pull the latest images:

```shell
$ cd /your/peertube/directory
$ docker-compose pull
```

Stop, delete the containers and internal volumes (to invalidate static client files shared by `peertube` and `webserver` containers):

```shell
$ docker-compose down -v
```

Rerun PeerTube:

```shell
$ docker-compose up -d
```

## Build

### Production

```shell
$ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
$ cd /tmp/peertube
$ docker build . -f ./support/docker/production/Dockerfile.bullseye
```

### Development

We don't have a Docker image for development. See [the CONTRIBUTING guide](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#develop) for more information on how you can hack PeerTube!
Commit	Line	Data
	1	# Docker guide
	2
	3	This guide requires [docker](https://www.docker.com/community-edition) and
	4	[docker-compose](https://docs.docker.com/compose/install/).
	5
	6	## Install
	7
	8	PeerTube does not support webserver host change. Keep in mind your domain
	9	name is definitive after your first PeerTube start.
	10
	11	#### Go to your workdir
	12
	13	_note_: the guide that follows assumes an empty workdir, but you can also clone the repository, use the master branch and `cd support/docker/production`.
	14
	15	```shell
	16	cd /your/peertube/directory
	17	```
	18
	19	#### Get the latest Compose file
	20
	21	```shell
	22	curl https://raw.githubusercontent.com/chocobozzz/PeerTube/master/support/docker/production/docker-compose.yml > docker-compose.yml
	23	```
	24
	25	View the source of the file you're about to download: [docker-compose.yml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/docker-compose.yml)
	26
	27	#### Get the latest env_file
	28
	29	```shell
	30	curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/docker/production/.env > .env
	31	```
	32
	33	View the source of the file you're about to download: [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env)
	34
	35	#### Tweak the `docker-compose.yml` file there according to your needs
	36
	37	```shell
	38	sudo nano docker-compose.yml
	39	```
	40
	41	#### Then tweak the `.env` file to change the environment variables settings
	42
	43	```shell
	44	sudo nano .env
	45	```
	46
	47	In the downloaded example [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env), you must replace:
	48	- `<MY POSTGRES USERNAME>`
	49	- `<MY POSTGRES PASSWORD>`
	50	- `<MY DOMAIN>` without 'https://'
	51	- `<MY EMAIL ADDRESS>`
	52	- `<MY PEERTUBE SECRET>`
	53
	54	Other environment variables are used in
	55	[/support/docker/production/config/custom-environment-variables.yaml](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/custom-environment-variables.yaml) and can be
	56	intuited from usage.
	57
	58	#### Webserver
	59
	60	The docker compose file includes a configured web server. You can skip this part and comment the appropriate section in the docker compose if you use another webserver/proxy.
	61
	62	Install the template that the nginx container will use.
	63	The container will generate the configuration by replacing `${WEBSERVER_HOST}` and `${PEERTUBE_HOST}` using your docker compose env file.
	64
	65	```shell
	66	mkdir -p docker-volume/nginx
	67	curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/nginx/peertube > docker-volume/nginx/peertube
	68	```
	69
	70	You need to manually generate the first SSL/TLS certificate using Let's Encrypt:
	71
	72	```shell
	73	mkdir -p docker-volume/certbot
	74	docker run -it --rm --name certbot -p 80:80 -v "$(pwd)/docker-volume/certbot/conf:/etc/letsencrypt" certbot/certbot certonly --standalone
	75	```
	76
	77	A dedicated container in the docker-compose will automatically renew this certificate and reload nginx.
	78
	79
	80	#### Test your setup
	81
	82	_note_: Newer versions of compose are called with `docker compose` instead of `docker-compose`, so remove the dash in all steps that use this command if you are getting errors.
	83
	84	Run your containers:
	85
	86	```shell
	87	docker-compose up
	88	```
	89
	90	#### Obtaining your automatically-generated admin credentials
	91
	92	You can change the automatically created password for user root by running this command from peertube's root directory:
	93	```shell
	94	docker-compose exec -u peertube peertube npm run reset-password -- -u root
	95	```
	96
	97	You can also grep your peertube container's logs for the default `root` password. You're going to want to run `docker-compose logs peertube \| grep -A1 root` to search the log output for your new PeerTube's instance admin credentials which will look something like this.
	98
	99	```bash
	100	$ docker-compose logs peertube \| grep -A1 root
	101
	102	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.082 info: Username: root
	103	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
	104	```
	105
	106	#### Obtaining Your Automatically Generated DKIM DNS TXT Record
	107
	108	[DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) signature sending and RSA keys generation are enabled by the default Postfix image `mwader/postfix-relay` with [OpenDKIM](http://www.opendkim.org/).
	109
	110	Run `cat ./docker-volume/opendkim/keys//.txt` to display your DKIM DNS TXT Record containing the public key to configure to your domain :
	111
	112	```bash
	113	$ cat ./docker-volume/opendkim/keys//.txt
	114
	115	peertube._domainkey.mydomain.tld. IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
	116	"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dx7wLGPFVaxVQ4TGym/eF89aQ8oMxS9v5BCc26Hij91t2Ci8Fl12DHNVqZoIPGm+9tTIoDVDFEFrlPhMOZl8i4jU9pcFjjaIISaV2+qTa8uV1j3MyByogG8pu4o5Ill7zaySYFsYB++cHJ9pjbFSC42dddCYMfuVgrBsLNrvEi3dLDMjJF5l92Uu8YeswFe26PuHX3Avr261n"
	117	"j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" ) ; ----- DKIM key peertube for mydomain.tld
	118	```
	119
	120	#### Administrator password
	121
	122	See the production guide ["Administrator" section](https://docs.joinpeertube.org/install/any-os#administrator)
	123
	124	#### What now?
	125
	126	See the production guide ["What now" section](https://docs.joinpeertube.org/install/any-os#what-now).
	127
	128	## Upgrade
	129
	130	*Check the changelog (in particular the IMPORTANT NOTES* section):** https://github.com/Chocobozzz/PeerTube/blob/develop/CHANGELOG.md
	131
	132	Pull the latest images:
	133
	134	```shell
	135	$ cd /your/peertube/directory
	136	$ docker-compose pull
	137	```
	138
	139	Stop, delete the containers and internal volumes (to invalidate static client files shared by `peertube` and `webserver` containers):
	140
	141	```shell
	142	$ docker-compose down -v
	143	```
	144
	145	Rerun PeerTube:
	146
	147	```shell
	148	$ docker-compose up -d
	149	```
	150
	151	## Build
	152
	153	### Production
	154
	155	```shell
	156	$ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
	157	$ cd /tmp/peertube
	158	$ docker build . -f ./support/docker/production/Dockerfile.bullseye
	159	```
	160
	161	### Development
	162
	163	We don't have a Docker image for development. See [the CONTRIBUTING guide](https://github.com/Chocobozzz/PeerTube/blob/develop/.github/CONTRIBUTING.md#develop) for more information on how you can hack PeerTube!