[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>`
- `<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

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=technologist-administrator)

#### What now?

See the production guide ["What now" section](https://docs.joinpeertube.org/install-any-os?id=tada-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	- `<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	Run your containers:
	83
	84	```shell
	85	docker-compose up
	86	```
	87
	88	#### Obtaining your automatically-generated admin credentials
	89
	90	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.
	91
	92	```bash
	93	$ docker-compose logs peertube \| grep -A1 root
	94
	95	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.082 info: Username: root
	96	peertube_1 \| [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
	97	```
	98
	99	#### Obtaining Your Automatically Generated DKIM DNS TXT Record
	100
	101	[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/).
	102
	103	Run `cat ./docker-volume/opendkim/keys//.txt` to display your DKIM DNS TXT Record containing the public key to configure to your domain :
	104
	105	```bash
	106	$ cat ./docker-volume/opendkim/keys//.txt
	107
	108	peertube._domainkey.mydomain.tld. IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
	109	"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0Dx7wLGPFVaxVQ4TGym/eF89aQ8oMxS9v5BCc26Hij91t2Ci8Fl12DHNVqZoIPGm+9tTIoDVDFEFrlPhMOZl8i4jU9pcFjjaIISaV2+qTa8uV1j3MyByogG8pu4o5Ill7zaySYFsYB++cHJ9pjbFSC42dddCYMfuVgrBsLNrvEi3dLDMjJF5l92Uu8YeswFe26PuHX3Avr261n"
	110	"j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" ) ; ----- DKIM key peertube for mydomain.tld
	111	```
	112
	113	#### Administrator password
	114
	115	See the production guide ["Administrator" section](https://docs.joinpeertube.org/install-any-os?id=technologist-administrator)
	116
	117	#### What now?
	118
	119	See the production guide ["What now" section](https://docs.joinpeertube.org/install-any-os?id=tada-what-now).
	120
	121	## Upgrade
	122
	123	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).
	124
	125	Pull the latest images:
	126
	127	```shell
	128	$ cd /your/peertube/directory
	129	$ docker-compose pull
	130	```
	131
	132	Stop, delete the containers and internal volumes (to invalidate static client files shared by `peertube` and `webserver` containers):
	133
	134	```shell
	135	$ docker-compose down -v
	136	```
	137
	138	Rerun PeerTube:
	139
	140	```shell
	141	$ docker-compose up -d
	142	```
	143
	144	## Build
	145
	146	### Production
	147
	148	```shell
	149	$ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
	150	$ cd /tmp/peertube
	151	$ docker build . -f ./support/docker/production/Dockerfile.bullseye
	152	```
	153
	154	### Development
	155
	156	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!