Merge branch 'release/3.2.0' into develop

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

diff --git a/support/doc/docker.md b/support/doc/docker.md
index cf3a0db0b6b555304645c2894b05b56efaf96326..d83ee3997e7edf99a8c545a6834f9d72c39f8187 100644 (file)
--- a/support/doc/docker.md
+++ b/support/doc/docker.md
@@ -3,11 +3,9 @@
 This guide requires [docker](https://www.docker.com/community-edition) and
 [docker-compose](https://docs.docker.com/compose/install/).
 
 This guide requires [docker](https://www.docker.com/community-edition) and
 [docker-compose](https://docs.docker.com/compose/install/).
 

-## Production
+## Install

 
 

-### Install
-
-**PeerTube does not support webserver host change**. Keep in mind your domain 
+**PeerTube does not support webserver host change**. Keep in mind your domain

 name is definitive after your first PeerTube start.
 
 #### Go to your workdir
 name is definitive after your first PeerTube start.
 
 #### Go to your workdir


@@ -21,18 +19,18 @@ cd /your/peertube/directory
 #### Get the latest Compose file
 
 ```shell
 #### Get the latest Compose file
 
 ```shell

-curl https://raw.githubusercontent.com/chocobozzz/PeerTube/master/support/docker/production/docker-compose.yml > docker-compose.yml
+curl https://raw.githubusercontent.com/chocobozzz/PeerTube/develop/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)
+View the source of the file you're about to download: [docker-compose.yml](https://github.com/Chocobozzz/PeerTube/blob/develop/support/docker/production/docker-compose.yml)

 
 #### Get the latest env_file
 
 ```shell
 
 #### Get the latest env_file
 
 ```shell

-curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/master/support/docker/production/.env > .env
+curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/develop/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)
+View the source of the file you're about to download: [.env](https://github.com/Chocobozzz/PeerTube/blob/develop/support/docker/production/.env)

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


@@ -46,30 +44,47 @@ $EDITOR ./docker-compose.yml
 $EDITOR ./.env
 ```
 
 $EDITOR ./.env
 ```
 

-In the downloaded example [.env](https://github.com/Chocobozzz/PeerTube/blob/master/support/docker/production/.env), you must replace:
+In the downloaded example [.env](https://github.com/Chocobozzz/PeerTube/blob/develop/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
 - `<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
+[/support/docker/production/config/custom-environment-variables.yaml](https://github.com/Chocobozzz/PeerTube/blob/develop/support/docker/production/config/custom-environment-variables.yaml) and can be

 intuited from usage.
 
 intuited from usage.
 

-#### Testing local Docker setup
+#### 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.

 
 

-To test locally your Docker setup, you must add your domain (`<MY DOMAIN>`) in `/etc/hosts`:
+```shell
+mkdir -p docker-volume/nginx
+curl https://raw.githubusercontent.com/Chocobozzz/PeerTube/develop/support/nginx/peertube > docker-volume/nginx/peertube

 ```
 ```

-127.0.0.1       localhost   mydomain.tld
+
+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

 ```
 
 ```
 

-#### You can use the regular `up` command to set it up
+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
 ```
 
 
 ```shell
 docker-compose up
 ```
 

-### Obtaining your automatically-generated admin credentials
+#### 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.
 
 
 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.
 


@@ -80,11 +95,11 @@ 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
 ```
 
 peertube_1  | [example.com:443] 2019-11-16 04:26:06.083 info: User password: abcdefghijklmnop
 ```
 

-### Obtaining Your Automatically Generated DKIM DNS TXT Record
+#### 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/).
 
 
 [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 : 
+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
 
 ```bash
 $ cat ./docker-volume/opendkim/keys/*/*.txt


@@ -94,27 +109,40 @@ peertube._domainkey.mydomain.tld.  IN      TXT     ( "v=DKIM1; h=sha256; k=rsa; "
          "j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" )  ; ----- DKIM key peertube for mydomain.tld
 ```
 
          "j5joTnYwat4387VEUyGUnZ0aZxCERi+ndXv2/wMJ0tizq+a9+EgqIb+7lkUc2XciQPNuTujM25GhrQBEKznvHyPA6fHsFheymOuB763QpkmnQQLCxyLygAY9mE/5RY+5Q6J9oDOQIDAQAB" )  ; ----- DKIM key peertube for mydomain.tld
 ```
 

-### Administrator password
+#### Administrator password

 
 

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

 
 

-### What now?
+#### What now?

 
 

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

 
 

-### Upgrade
+## Upgrade

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

-Pull the latest images and rerun PeerTube:
+Pull the latest images:

 
 ```shell
 $ cd /your/peertube/directory
 $ docker-compose pull
 
 ```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
 ```
 
 $ docker-compose up -d
 ```
 

-## Build your own Docker image
+## Build
+
+### Production

 
 ```shell
 $ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube
 
 ```shell
 $ git clone https://github.com/chocobozzz/PeerTube /tmp/peertube


@@ -122,6 +150,6 @@ $ cd /tmp/peertube
 $ docker build . -f ./support/docker/production/Dockerfile.buster
 ```
 
 $ docker build . -f ./support/docker/production/Dockerfile.buster
 ```
 

-## Development
+### Development

 
 

-We don't have a Docker image for development. See [the CONTRIBUTING guide](https://github.com/Chocobozzz/PeerTube/blob/master/.github/CONTRIBUTING.md#develop) for more information on how you can hack PeerTube!
+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!