[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
$EDITOR ./docker-compose.yml
```

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

```shell
$EDITOR ./.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>`

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

Run your containers:

```shell
docker-compose up
```

#### Obtaining your automatically-generated admin credentials

Now that you've installed your PeerTube instance you'll want to grep your peertube container's logs for the `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?id=administrator)

#### What now?

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

## Upgrade

**Important:** Before upgrading, check you have all the `storage` fields in your [production.yaml file](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/production.yaml).

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	$EDITOR ./docker-compose.yml
	39	```
	40
	41	#### Then tweak the `.env` file to change the environment variables settings
	42
	43	```shell
	44	$EDITOR ./.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
	53	Other environment variables are used in
	54	[/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
	55	intuited from usage.
	56
	57	#### Webserver
	58
	59	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.
	60
	61	Install the template that the nginx container will use.
	62	The container will generate the configuration by replacing `${WEBSERVER_HOST}` and `${PEERTUBE_HOST}` using your docker compose env file.
	63
	64	```shell
	65	mkdir -p docker-volume/nginx
	66	curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/nginx/peertube > docker-volume/nginx/peertube
	67	```
	68
	69	You need to manually generate the first SSL/TLS certificate using Let's Encrypt:
	70
	71	```shell
	72	mkdir -p docker-volume/certbot
	73	docker run -it --rm --name certbot -p 80:80 -v "$(pwd)/docker-volume/certbot/conf:/etc/letsencrypt" certbot/certbot certonly --standalone
	74	```
	75
	76	A dedicated container in the docker-compose will automatically renew this certificate and reload nginx.
	77
	78
	79	#### Test your setup
	80
	81	Run your containers:
	82
	83	```shell
	84	docker-compose up
	85	```
	86
	87	#### Obtaining your automatically-generated admin credentials
	88
	89	Now that you've installed your PeerTube instance you'll want to grep your peertube container's logs for the `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.
	90
	91	```bash
	92	$ docker-compose logs peertube \| grep -A1 root
	93
	94	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.082 info: Username: root
	95	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
	96	```
	97
	98	#### Obtaining Your Automatically Generated DKIM DNS TXT Record
	99
	100	[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/).
	101
	102	Run `cat ./docker-volume/opendkim/keys//.txt` to display your DKIM DNS TXT Record containing the public key to configure to your domain :
	103
	104	```bash
	105	$ cat ./docker-volume/opendkim/keys//.txt
	106
	107	peertube._domainkey.mydomain.tld. IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
	108	"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dx7wLGPFVaxVQ4TGym/eF89aQ8oMxS9v5BCc26Hij91t2Ci8Fl12DHNVqZoIPGm+9tTIoDVDFEFrlPhMOZl8i4jU9pcFjjaIISaV2+qTa8uV1j3MyByogG8pu4o5Ill7zaySYFsYB++cHJ9pjbFSC42dddCYMfuVgrBsLNrvEi3dLDMjJF5l92Uu8YeswFe26PuHX3Avr261n"
	109	"j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" ) ; ----- DKIM key peertube for mydomain.tld
	110	```
	111
	112	#### Administrator password
	113
	114	See the production guide ["Administrator" section](https://docs.joinpeertube.org/install-any-os?id=administrator)
	115
	116	#### What now?
	117
	118	See the production guide ["What now" section](https://docs.joinpeertube.org/install-any-os?id=what-now).
	119
	120	## Upgrade
	121
	122	Important: Before upgrading, check you have all the `storage` fields in your [production.yaml file](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/config/production.yaml).
	123
	124	Pull the latest images:
	125
	126	```shell
	127	$ cd /your/peertube/directory
	128	$ docker-compose pull
	129	```
	130
	131	Stop, delete the containers and internal volumes (to invalidate static client files shared by `peertube` and `webserver` containers):
	132
	133	```shell
	134	$ docker-compose down -v
	135	```
	136
	137	Rerun PeerTube:
	138
	139	```shell
	140	$ docker-compose up -d
	141	```
	142
	143	## Build
	144
	145	### Production
	146
	147	```shell
	148	$ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
	149	$ cd /tmp/peertube
	150	$ docker build . -f ./support/docker/production/Dockerfile.bullseye
	151	```
	152
	153	### Development
	154
	155	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!