Update sumperdump Docker readme to match this image properties

1 files changed, 64 insertions, 38 deletions

diff --git a/contrib/docker/README.md b/contrib/docker/README.md
index c15517d0e0..8ba5f79692 100644
--- a/contrib/docker/README.md
+++ b/contrib/docker/README.md
@@ -1,5 +1,12 @@
 # Synapse Docker
 
+This Docker image will run Synapse as a single process. It does not provide any
+database server or TURN server that you should run separately.
+
+If you run a Postgres server, you should simply have it in the same Compose
+project or set the proper environment variables and the image will automatically
+use that server.
+
 ## Build
 
 Build the docker image with the `docker build` command from the root of the synapse repository.
@@ -10,54 +17,29 @@ docker build -t matrixdotorg/synapse:v0.22.1 .
 
 The `-t` option sets the image tag. Official images are tagged `matrixdotorg/synapse:<version>` where `<version>` is the same as the release tag in the synapse git repository.
 
-## Configure
+You may have a local Python wheel cache available, in which case copy the relevant packages in the ``cache/`` directory at the root of the project.
 
-Synapse provides a command for generating homeserver configuration files. These are a good starting point for setting up your own deployment.
+## Run
 
-The documentation below will refer to a `CONFIG_PATH` shell variable. This is a path to a directory where synapse configuration will be stored. It needs to be mapped into the container as a volume at `/synapse/config/` as can be seen in the example `docker run` command.
+It is recommended that you use Docker Compose to run your containers, including
+this image and a Postgres server. A sample ``docker-compose.yml`` is provided,
+with example labels for a reverse proxy and other artifacts.
 
-Docker container environment variables:
-* `GENERATE_CONFIG` - Set this to any non-empty string, such as `yes`, to trigger generation of configuration files. Existing files in the `CONFIG_PATH` will **not** be overwritten.
-* `POSTGRES_DATABASE` - The database name for the synapse postgres database. [default: `synapse`]
-* `POSTGRES_HOST` - The host of the postgres database if you wish to use postgresql instead of sqlite3. [default: `postgres` which is useful when using a container on the same docker network in a compose file where the postgres service is called `postgres`] **NOTE**: `localhost` and `127.0.0.1` refer to the container itself unless running the container with `host` networking.
-* `POSTGRES_PASSWORD` - The password for the synapse postgres database. **If this is set then postgres will be used instead of sqlite3.** [default: none] **NOTE**: You are highly encouraged to use postgresql! Please use the compose file to make it easier to deploy.
-* `POSTGRES_USER` - The user for the synapse postgres database. [default: `postgres`]
-* `REPORT_STATS` - Whether to send anonymous usage statistics back to the Matrix project which helps us to get funding! Must be `yes` or `no`. [default: `yes`]
-* `SERVER_NAME` - The domain used for the Matrix homeserver. If you intend to run this synapse instance on a public domain, use that domain. [default: `localhost`]
+Then, to run the server:
 
 ```
-CONFIG_PATH=/my/magical/config/path/
-mkdir -p ${CONFIG_PATH}
-docker run \
-    --rm \
-    -e GENERATE_CONFIG=yes \
-    -e POSTGRES_PASSWORD=MyVerySecretPassword \
-    -e REPORT_STATS=yes \
-    -e SERVER_NAME=example.com \
-    -v ${CONFIG_PATH}:/synapse/config/ \
-    matrixdotorg/synapse:v0.22.1
+docker-compose up -d
 ```
 
-This will create a temporary container from the image and use the synapse code for generating configuration files and TLS keys and certificates for the specified `SERVER_NAME` domain. The files are written to `CONFIG_PATH`.
+In the case you specified a custom path for you configuration file and wish to
+generate a fresh ``homeserver.yaml``, simply run:
 
-## Run
-
-**NOTE**: If you are not using postgresql and are using sqlite3 as your database, you will need to make a directory to store the sqlite3 database file in and then mount this volume into the container at `/synapse/data/`. As it is so easy to use postgresql, when using Docker containers, this is not documented to somewhat discourage it. Choose a `POSTGRES_PASSWORD` instead.
-
-### Docker Compose
-
-A `docker-compose.yaml` file is included to ease deployment of the basic synapse and postgres setup. Remember to set a `POSTGRES_PASSWORD` when generating your configuration above. You will need it for running the containers in the composition.
-
-From the `docker/` subdirectory of the synapse repository:
 ```
-CONFIG_PATH=/my/magical/config/path/
-POSTGRES_PASSWORD=MyVerySecretPassword \
-docker-compose \
-    -p synapse \
-    up -d
+docker-compose run synapse generate
 ```
 
-### Docker
+If you do not wish to use Compose, you may still run this image using plain
+Docker commands:
 
 Note that the following is just a guideline and you may need to add parameters to the docker run command to account for the network situation with your postgres database.
 
@@ -65,6 +47,50 @@ Note that the following is just a guideline and you may need to add parameters t
 docker run \
     -d \
     --name synapse \
-    -v ${CONFIG_PATH}:/synapse/config/ \
+    -v ${DATA_PATH}:/data \
+    -e SYNAPSE_SERVER_NAME=my.matrix.host \
     matrixdotorg/synapse:v0.22.1
 ```
+
+
+## Volumes
+
+The image expects a single volue, located at ``/data``, that will hold:
+
+* temporary files during uploads;
+* uploaded media and thumbnais;
+* the SQLite database if you do not configure postgres.
+
+## Environment
+
+If you do not specify a custom path for the configuration file, a very generic
+file will be generated, based on the following environment settings.
+These are a good starting point for setting up your own deployment.
+
+Synapse specific settings:
+
+* ``SYNAPSE_SERVER_NAME`` (mandatory), the current server public hostname.
+* ``SYNAPSE_CONFIG_PATH``, path to a custom config file (will ignore all
+  other options then).
+* ``SYNAPSE_NO_TLS``, set this variable to disable TLS in Synapse (use this if
+  you run your own TLS-capable reverse proxy).
+* ``SYNAPSE_WEB_CLIENT``, set this variable to enable the embedded Web client.
+* ``SYNAPSE_ENABLE_REGISTRATION``, set this variable to enable registration on
+  the Synapse instance.
+* ``SYNAPSE_ALLOW_GUEST``, set this variable to allow guest joining this server.
+* ``SYNAPSE_EVENT_CACHE_SIZE``, the event cache size [default `10K`].
+* ``SYNAPSE_REPORT_STATS``, set this variable to `yes` to enable anonymous
+  statistics reporting back to the Matrix project which helps us to get funding.
+
+Shared secrets, these will be initialized to random values if not set:
+
+* ``SYNAPSE_REGISTRATION_SHARED_SECRET``, secret for registrering users if
+  registration is disable.
+* ``SYNAPSE_MACAROON_SECRET_KEY``, secret for Macaroon.
+
+Database specific values (will use SQLite if not set):
+
+* `POSTGRES_DATABASE` - The database name for the synapse postgres database. [default: `matrix`]
+* `POSTGRES_HOST` - The host of the postgres database if you wish to use postgresql instead of sqlite3. [default: `db` which is useful when using a container on the same docker network in a compose file where the postgres service is called `db`]
+* `POSTGRES_PASSWORD` - The password for the synapse postgres database. **If this is set then postgres will be used instead of sqlite3.** [default: none] **NOTE**: You are highly encouraged to use postgresql! Please use the compose file to make it easier to deploy.
+* `POSTGRES_USER` - The user for the synapse postgres database. [default: `matrix`]