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

# Docker guide

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

```shell
docker compose version # Must be > 2.x.x
```

## 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

:::info
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

::: info
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

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