From 9a87b8aaf7c66380cfbdfdf35bb24f24eeef28f5 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Sun, 4 Feb 2018 15:27:32 +0100 Subject: Update sumperdump Docker readme to match this image properties --- contrib/docker/README.md | 102 +++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 38 deletions(-) (limited to 'contrib/docker/README.md') 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:` where `` 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`] -- cgit 1.4.1 From f72c9c1fb650c7f3bac4d77d4e24fa0469d09ebb Mon Sep 17 00:00:00 2001 From: kaiyou Date: Sun, 4 Feb 2018 16:18:40 +0100 Subject: Fix multiple typos --- MANIFEST.in | 1 + contrib/docker/README.md | 19 ++++++++++++------- contrib/docker/docker-compose.yml | 7 ++++--- 3 files changed, 17 insertions(+), 10 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/MANIFEST.in b/MANIFEST.in index afb60e12ee..8c9a57a9ca 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -25,6 +25,7 @@ recursive-include synapse/static *.js exclude jenkins.sh exclude jenkins*.sh exclude jenkins* +exclude Dockerfile recursive-exclude jenkins *.sh prune .github diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 8ba5f79692..73e53e4306 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -23,7 +23,7 @@ You may have a local Python wheel cache available, in which case copy the releva 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. +including example labels for reverse proxying and other artifacts. Then, to run the server: @@ -35,13 +35,13 @@ In the case you specified a custom path for you configuration file and wish to generate a fresh ``homeserver.yaml``, simply run: ``` -docker-compose run synapse generate +docker-compose run --rm synapse generate ``` 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. +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. ``` docker run \ @@ -55,7 +55,7 @@ docker run \ ## Volumes -The image expects a single volue, located at ``/data``, that will hold: +The image expects a single volume, located at ``/data``, that will hold: * temporary files during uploads; * uploaded media and thumbnais; @@ -63,10 +63,15 @@ The image expects a single volue, located at ``/data``, that will hold: ## Environment -If you do not specify a custom path for the configuration file, a very generic +Unless you 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. +Global settings: + +* ``UID``, the user id Synapse will run as [default 991] +* ``GID``, the group id Synapse will run as [default 991] + Synapse specific settings: * ``SYNAPSE_SERVER_NAME`` (mandatory), the current server public hostname. diff --git a/contrib/docker/docker-compose.yml b/contrib/docker/docker-compose.yml index b8f9741f05..727743effa 100644 --- a/contrib/docker/docker-compose.yml +++ b/contrib/docker/docker-compose.yml @@ -1,4 +1,4 @@ -# This compose file is compatible with Copose itself, it might need some +# This compose file is compatible with Compose itself, it might need some # adjustments to run properly with stack. version: '3' @@ -18,10 +18,11 @@ services: - ./files:/data depends_on: - db - # One may either expose ports directly + # In order to expose Synapse, remove one of the following, you might for + # instance expose the TLS port directly: ports: - 8448:8448/tcp - # ... or use a reverse proxy, here is an example for traefik + # ... or use a reverse proxy, here is an example for traefik: labels: - traefik.enable=true - traefik.frontend.rule=Host:my.matrix.Host -- cgit 1.4.1 From 81010a126e9bbcce018b104921ff5221a67f99cc Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 21:28:15 +0100 Subject: Add dynamic recaptcha configuration in the Docker image --- contrib/docker/README.md | 4 ++++ contrib/docker/conf/homeserver.yaml | 7 +++++++ 2 files changed, 11 insertions(+) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 73e53e4306..f4bc78908d 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -86,6 +86,10 @@ Synapse specific settings: * ``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. +* ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public + key in order to enable recaptcha upon registration +* ``SYNAPSE_RECAPTCHA_PRIVATE_KEY``, set this variable to the recaptcha private + key in order to enable recaptcha upon registration Shared secrets, these will be initialized to random values if not set: diff --git a/contrib/docker/conf/homeserver.yaml b/contrib/docker/conf/homeserver.yaml index 7450cc1228..6f1de24aad 100644 --- a/contrib/docker/conf/homeserver.yaml +++ b/contrib/docker/conf/homeserver.yaml @@ -112,10 +112,17 @@ max_spider_size: "10M" ## Captcha ## +{% if SYNAPSE_RECAPTCHA_PUBLIC_KEY %} +recaptcha_public_key: "{{ SYNAPSE_RECAPTCHA_PUBLIC_KEY }}" +recaptcha_private_key: "{{ SYNAPSE_RECAPTCHA_PRIVATE_KEY }}" +enable_registration_captcha: True +recaptcha_siteverify_api: "https://www.google.com/recaptcha/api/siteverify" +{% else %} recaptcha_public_key: "YOUR_PUBLIC_KEY" recaptcha_private_key: "YOUR_PRIVATE_KEY" enable_registration_captcha: False recaptcha_siteverify_api: "https://www.google.com/recaptcha/api/siteverify" +{% endif %} ## Turn ## -- cgit 1.4.1 From cd51931b62aef63dacf4d79cdfa5de56da4eeda6 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 21:53:53 +0100 Subject: Add dynamic TURN configuration in the Docker image --- contrib/docker/README.md | 7 +++++-- contrib/docker/conf/homeserver.yaml | 9 +++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index f4bc78908d..0da7b56628 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -87,9 +87,12 @@ Synapse specific settings: * ``SYNAPSE_REPORT_STATS``, set this variable to `yes` to enable anonymous statistics reporting back to the Matrix project which helps us to get funding. * ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public - key in order to enable recaptcha upon registration + key in order to enable recaptcha upon registration. * ``SYNAPSE_RECAPTCHA_PRIVATE_KEY``, set this variable to the recaptcha private - key in order to enable recaptcha upon registration + key in order to enable recaptcha upon registration. +* ``SYNAPSE_TURN_URIS``, set this variable to the coma-separated list of TURN + uris to enable TURN for this homeserver. +* ``SYNAPSE_TURN_SECRET``, set this to the TURN shared secret if required. Shared secrets, these will be initialized to random values if not set: diff --git a/contrib/docker/conf/homeserver.yaml b/contrib/docker/conf/homeserver.yaml index 6f1de24aad..6f8fb24e5f 100644 --- a/contrib/docker/conf/homeserver.yaml +++ b/contrib/docker/conf/homeserver.yaml @@ -126,10 +126,19 @@ recaptcha_siteverify_api: "https://www.google.com/recaptcha/api/siteverify" ## Turn ## +{% if SYNAPSE_TURN_URIS %} +turn_uris: +{% for uri in SYNAPSE_TURN_URIS.split(',') %} - {{ uri }} +{% endfor %} +turn_shared_secret: "{{ SYNAPSE_TURN_SECRET }}" +turn_user_lifetime: "1h" +turn_allow_guests: True +{% else %} turn_uris: [] turn_shared_secret: "YOUR_SHARED_SECRET" turn_user_lifetime: "1h" turn_allow_guests: True +{% endif %} ## Registration ## -- cgit 1.4.1 From cf4ef60e287a6a61844ab260606721db2b7ee0cd Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 22:10:03 +0100 Subject: Document the cache factor environment variable for Docker --- contrib/docker/README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 0da7b56628..8b1e0afee6 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -84,6 +84,7 @@ Synapse specific settings: 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_CACHE_FACTOR``, the cache factor [default `0.5`]. * ``SYNAPSE_REPORT_STATS``, set this variable to `yes` to enable anonymous statistics reporting back to the Matrix project which helps us to get funding. * ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public -- cgit 1.4.1 From d8c7da5dca907bf65293b6b967200141cad69410 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 22:12:50 +0100 Subject: Fix a typo in the Docker README --- contrib/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 8b1e0afee6..624dca747a 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -58,7 +58,7 @@ docker run \ The image expects a single volume, located at ``/data``, that will hold: * temporary files during uploads; -* uploaded media and thumbnais; +* uploaded media and thumbnails; * the SQLite database if you do not configure postgres. ## Environment -- cgit 1.4.1 From f5364b47ec4b67a552976b9dbb9594d448744e30 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 22:14:40 +0100 Subject: Point to the 'latest' tag in the Docker documentation --- contrib/docker/README.md | 2 +- contrib/docker/docker-compose.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 624dca747a..87354b9bc3 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -49,7 +49,7 @@ docker run \ --name synapse \ -v ${DATA_PATH}:/data \ -e SYNAPSE_SERVER_NAME=my.matrix.host \ - matrixdotorg/synapse:v0.22.1 + matrixdotorg/synapse:latest ``` diff --git a/contrib/docker/docker-compose.yml b/contrib/docker/docker-compose.yml index 727743effa..3fb156db47 100644 --- a/contrib/docker/docker-compose.yml +++ b/contrib/docker/docker-compose.yml @@ -6,7 +6,7 @@ version: '3' services: synapse: - image: synapse + image: matrixdotorg/synapse:latest # Since snyapse does not retry to connect to the database, restart upon # failure restart: unless-stopped -- cgit 1.4.1 From 1ffd9cb93617fe9bb2367d575786c0ff222cd415 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Mon, 5 Feb 2018 23:13:27 +0100 Subject: Support loading application service files from /data/appservices/ --- contrib/docker/README.md | 7 ++++++- contrib/docker/conf/homeserver.yaml | 9 ++++++++- contrib/docker/start.py | 4 ++++ 3 files changed, 18 insertions(+), 2 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 87354b9bc3..c1724fe269 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -59,7 +59,12 @@ The image expects a single volume, located at ``/data``, that will hold: * temporary files during uploads; * uploaded media and thumbnails; -* the SQLite database if you do not configure postgres. +* the SQLite database if you do not configure postgres; +* the appservices configuration. + +In order to setup an application service, simply create an ``appservices`` +directory in the data volume and write the application service Yaml +configuration file there. Multiple application services are supported. ## Environment diff --git a/contrib/docker/conf/homeserver.yaml b/contrib/docker/conf/homeserver.yaml index 6f8fb24e5f..e5d3f965e4 100644 --- a/contrib/docker/conf/homeserver.yaml +++ b/contrib/docker/conf/homeserver.yaml @@ -128,7 +128,7 @@ recaptcha_siteverify_api: "https://www.google.com/recaptcha/api/siteverify" {% if SYNAPSE_TURN_URIS %} turn_uris: -{% for uri in SYNAPSE_TURN_URIS.split(',') %} - {{ uri }} +{% for uri in SYNAPSE_TURN_URIS.split(',') %} - "{{ uri }}" {% endfor %} turn_shared_secret: "{{ SYNAPSE_TURN_SECRET }}" turn_user_lifetime: "1h" @@ -167,7 +167,14 @@ room_invite_state_types: - "m.room.avatar" - "m.room.name" +{% if SYNAPSE_APPSERVICES %} +app_service_config_files: +{% for appservice in SYNAPSE_APPSERVICES %} - "{{ appservice }}" +{% endfor %} +{% else %} app_service_config_files: [] +{% endif %} + macaroon_secret_key: "{{ SYNAPSE_MACAROON_SECRET_KEY }}" expire_access_token: False diff --git a/contrib/docker/start.py b/contrib/docker/start.py index d3364e4226..8ade0f227d 100755 --- a/contrib/docker/start.py +++ b/contrib/docker/start.py @@ -4,6 +4,7 @@ import jinja2 import os import sys import subprocess +import glob convert = lambda src, dst, environ: open(dst, "w").write(jinja2.Template(open(src).read()).render(**environ)) mode = sys.argv[1] if len(sys.argv) > 1 else None @@ -26,6 +27,9 @@ for secret in ("SYNAPSE_REGISTRATION_SHARED_SECRET", "SYNAPSE_MACAROON_SECRET_KE print("Generating a random secret for {}".format(secret)) environ[secret] = os.urandom(32).encode("hex") +# Load appservices configurations +environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml") + # In generate mode, generate a configuration, missing keys, then exit if mode == "generate": os.execv("/usr/local/bin/python", args + ["--generate-config"]) -- cgit 1.4.1 From 63fd148724399d52f3435b1c172435d7cabcde4c Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 19:46:11 +0100 Subject: Make it clear that two modes are avaiable in the documentation, improve the compose file --- contrib/docker/README.md | 17 ++++++++++------- contrib/docker/docker-compose.yml | 12 ++++++++++-- 2 files changed, 20 insertions(+), 9 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index c1724fe269..197bad103e 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -12,7 +12,7 @@ use that server. Build the docker image with the `docker build` command from the root of the synapse repository. ``` -docker build -t matrixdotorg/synapse:v0.22.1 . +docker build -t matrixdotorg/synapse . ``` The `-t` option sets the image tag. Official images are tagged `matrixdotorg/synapse:` where `` is the same as the release tag in the synapse git repository. @@ -76,12 +76,17 @@ Global settings: * ``UID``, the user id Synapse will run as [default 991] * ``GID``, the group id Synapse will run as [default 991] +* ``SYNAPSE_CONFIG_PATH``, path to a custom config file -Synapse specific settings: +If ``SYNAPSE_CONFIG_PATH`` is set, you should generate a configuration file +then customize it manually. No other environment variable is required. + +Otherwise, a dynamic configuration file will be used. The following environment +variables are available for configuration: * ``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_REPORT_STATS``, (mandatory, ``yes`` or ``not``), enable anonymous + statistics reporting back to the Matrix project which helps us to get funding. * ``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. @@ -90,8 +95,6 @@ Synapse specific settings: * ``SYNAPSE_ALLOW_GUEST``, set this variable to allow guest joining this server. * ``SYNAPSE_EVENT_CACHE_SIZE``, the event cache size [default `10K`]. * ``SYNAPSE_CACHE_FACTOR``, the cache factor [default `0.5`]. -* ``SYNAPSE_REPORT_STATS``, set this variable to `yes` to enable anonymous - statistics reporting back to the Matrix project which helps us to get funding. * ``SYNAPSE_RECAPTCHA_PUBLIC_KEY``, set this variable to the recaptcha public key in order to enable recaptcha upon registration. * ``SYNAPSE_RECAPTCHA_PRIVATE_KEY``, set this variable to the recaptcha private @@ -100,7 +103,7 @@ Synapse specific settings: uris to enable TURN for this homeserver. * ``SYNAPSE_TURN_SECRET``, set this to the TURN shared secret if required. -Shared secrets, these will be initialized to random values if not set: +Shared secrets, that will be initialized to random values if not set: * ``SYNAPSE_REGISTRATION_SHARED_SECRET``, secret for registrering users if registration is disable. diff --git a/contrib/docker/docker-compose.yml b/contrib/docker/docker-compose.yml index 3fb156db47..b07984ea34 100644 --- a/contrib/docker/docker-compose.yml +++ b/contrib/docker/docker-compose.yml @@ -6,7 +6,7 @@ version: '3' services: synapse: - image: matrixdotorg/synapse:latest + image: docker.io/matrixdotorg/synapse:latest # Since snyapse does not retry to connect to the database, restart upon # failure restart: unless-stopped @@ -15,7 +15,12 @@ services: - SYNAPSE_SERVER_NAME=my.matrix.host - SYNAPSE_ENABLE_REGISTRATION=yes volumes: + # You may either store all the files in a local folder - ./files:/data + # .. or you may split this between different storage points + # - ./files:/data + # - /path/to/ssd:/data/uploads + # - /path/to/large_hdd:/data/media depends_on: - db # In order to expose Synapse, remove one of the following, you might for @@ -29,10 +34,13 @@ services: - traefik.port=8448 db: - image: postgres:latest + image: postgres:10-alpine # Change that password, of course! environment: - POSTGRES_USER=matrix - POSTGRES_PASSWORD=changeme volumes: + # You may store the database tables in a local folder.. - ./schemas:/var/lib/postgresql/data + # .. or store them on some high performance storage for better results + # - /path/to/ssd/storage:/var/lib/postfesql/data -- cgit 1.4.1 From 58df3a8c5dcf5de12bcf9190551dc8241d32b8a1 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 19:48:53 +0100 Subject: Add some documentation about high performance storage --- contrib/docker/README.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 197bad103e..3710afb0cf 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -31,11 +31,11 @@ Then, to run the server: docker-compose up -d ``` -In the case you specified a custom path for you configuration file and wish to +In the case you specify a custom path for you configuration file and wish to generate a fresh ``homeserver.yaml``, simply run: ``` -docker-compose run --rm synapse generate +docker-compose run --rm -e SYNAPSE_SERVER_NAME=my.matrix.host synapse generate ``` If you do not wish to use Compose, you may still run this image using plain @@ -62,6 +62,11 @@ The image expects a single volume, located at ``/data``, that will hold: * the SQLite database if you do not configure postgres; * the appservices configuration. +You are free to use separate volumes depending on storage endpoints at your +disposal. For instance, ``/data/media`` coud be stored on a large but low +performance hdd storage while other files could be stored on high performance +endpoints. + In order to setup an application service, simply create an ``appservices`` directory in the data volume and write the application service Yaml configuration file there. Multiple application services are supported. -- cgit 1.4.1 From b8a4dceb3cee6b69d1b1b882cef1f96a3ff6249f Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 20:41:41 +0100 Subject: Refactor the start script to better handle mandatory parameters --- contrib/docker/README.md | 2 +- contrib/docker/docker-compose.yml | 1 + contrib/docker/start.py | 56 +++++++++++++++++++++++---------------- 3 files changed, 35 insertions(+), 24 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 3710afb0cf..0493d2ee6e 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -90,7 +90,7 @@ Otherwise, a dynamic configuration file will be used. The following environment variables are available for configuration: * ``SYNAPSE_SERVER_NAME`` (mandatory), the current server public hostname. -* ``SYNAPSE_REPORT_STATS``, (mandatory, ``yes`` or ``not``), enable anonymous +* ``SYNAPSE_REPORT_STATS``, (mandatory, ``yes`` or ``no``), enable anonymous statistics reporting back to the Matrix project which helps us to get funding. * ``SYNAPSE_NO_TLS``, set this variable to disable TLS in Synapse (use this if you run your own TLS-capable reverse proxy). diff --git a/contrib/docker/docker-compose.yml b/contrib/docker/docker-compose.yml index b07984ea34..3d0b3c0ea4 100644 --- a/contrib/docker/docker-compose.yml +++ b/contrib/docker/docker-compose.yml @@ -13,6 +13,7 @@ services: # See the readme for a full documentation of the environment settings environment: - SYNAPSE_SERVER_NAME=my.matrix.host + - SYNAPSE_REPORT_STATS=no - SYNAPSE_ENABLE_REGISTRATION=yes volumes: # You may either store all the files in a local folder diff --git a/contrib/docker/start.py b/contrib/docker/start.py index 13a10a11bb..32142bbe00 100755 --- a/contrib/docker/start.py +++ b/contrib/docker/start.py @@ -6,42 +6,52 @@ import sys import subprocess import glob +# Utility functions convert = lambda src, dst, environ: open(dst, "w").write(jinja2.Template(open(src).read()).render(**environ)) -mode = sys.argv[1] if len(sys.argv) > 1 else None -environ = os.environ.copy() -# Check mandatory parameters and build the base start arguments -if "SYNAPSE_SERVER_NAME" not in environ: - print("Environment variable SYNAPSE_SERVER_NAME is mandatory, exiting.") - sys.exit(2) - -ownership = "{}:{}".format(environ.get("UID", 991), environ.get("GID", 991)) -args = ["python", "-m", "synapse.app.homeserver", - "--server-name", environ.get("SYNAPSE_SERVER_NAME"), - "--report-stats", environ.get("SYNAPSE_REPORT_STATS", "no"), - "--config-path", environ.get("SYNAPSE_CONFIG_PATH", "/compiled/homeserver.yaml")] +def check_arguments(environ, args): + for argument in args: + if argument not in environ: + print("Environment variable %s is mandatory, exiting." % argument) + sys.exit(2) -# Generate any missing shared secret -for secret in ("SYNAPSE_REGISTRATION_SHARED_SECRET", "SYNAPSE_MACAROON_SECRET_KEY"): - if secret not in environ: - print("Generating a random secret for {}".format(secret)) - environ[secret] = os.urandom(32).encode("hex") +def generate_secrets(environ, secrets): + for secret in secrets: + if secret not in environ: + print("Generating a random secret for {}".format(secret)) + environ[secret] = os.urandom(32).encode("hex") -# Load appservices configurations -environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml") +# Prepare the configuration +mode = sys.argv[1] if len(sys.argv) > 1 else None +environ = os.environ.copy() +ownership = "{}:{}".format(environ.get("UID", 991), environ.get("GID", 991)) +args = ["python", "-m", "synapse.app.homeserver"] # In generate mode, generate a configuration, missing keys, then exit if mode == "generate": - os.execv("/usr/local/bin/python", args + ["--generate-config"]) + check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS", "SYNAPSE_CONFIG_PATH")) + args += [ + "--server-name", environ["SYNAPSE_SERVER_NAME"], + "--report-stats", environ["SYNAPSE_REPORT_STATS"], + "--config-path", environ["SYNAPSE_CONFIG_PATH"], + "--generate-config" + ] + os.execv("/usr/local/bin/python", args) # In normal mode, generate missing keys if any, then run synapse else: # Parse the configuration file - if "SYNAPSE_CONFIG_PATH" not in environ: + if "SYNAPSE_CONFIG_PATH" in environ: + args += ["--config-path", environ["SYNAPSE_CONFIG_PATH"]] + else: + check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS")) + generate_secrets(environ, ("SYNAPSE_REGISTRATION_SHARED_SECRET", "SYNAPSE_MACAROON_SECRET_KEY")) + environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml") if not os.path.exists("/compiled"): os.mkdir("/compiled") convert("/conf/homeserver.yaml", "/compiled/homeserver.yaml", environ) - convert("/conf/log.config", "/compiled/%s.log.config" % environ.get("SYNAPSE_SERVER_NAME"), environ) + convert("/conf/log.config", "/compiled/%s.log.config" % environ["SYNAPSE_SERVER_NAME"], environ) + subprocess.check_output(["chown", "-R", ownership, "/data"]) + args += ["--config-path", "/compiled/homeserver.yaml"] # Generate missing keys and start synapse subprocess.check_output(args + ["--generate-keys"]) - subprocess.check_output(["chown", "-R", ownership, "/data"]) os.execv("/sbin/su-exec", ["su-exec", ownership] + args) -- cgit 1.4.1 From 914a59cb8c12b25d77ed9a81e4543c23d7e10b5e Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 20:43:45 +0100 Subject: Disable the Web client in the Docker image --- contrib/docker/README.md | 1 - contrib/docker/conf/homeserver.yaml | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 0493d2ee6e..9f40dc0d58 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -94,7 +94,6 @@ variables are available for configuration: statistics reporting back to the Matrix project which helps us to get funding. * ``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. diff --git a/contrib/docker/conf/homeserver.yaml b/contrib/docker/conf/homeserver.yaml index 1ca1fe991f..19a2cbad29 100644 --- a/contrib/docker/conf/homeserver.yaml +++ b/contrib/docker/conf/homeserver.yaml @@ -12,7 +12,7 @@ tls_fingerprints: [] server_name: "{{ SYNAPSE_SERVER_NAME }}" pid_file: /homeserver.pid -web_client: {{ "True" if SYNAPSE_WEB_CLIENT else "False" }} +web_client: False soft_file_limit: 0 ## Ports ## @@ -26,7 +26,7 @@ listeners: tls: true x_forwarded: false resources: - - names: [client, webclient] + - names: [client] compress: true - names: [federation] # Federation APIs compress: false @@ -39,7 +39,7 @@ listeners: x_forwarded: false resources: - - names: [client, webclient] + - names: [client] compress: true - names: [federation] compress: false -- cgit 1.4.1 From ef1f8d4be6e970043b8283f5caa1ca764652ad56 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 20:53:12 +0100 Subject: Enable email server configuration from environment variables --- contrib/docker/README.md | 7 +++++++ contrib/docker/conf/homeserver.yaml | 33 +++++++++++++++++---------------- 2 files changed, 24 insertions(+), 16 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 9f40dc0d58..b74c72698c 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -119,3 +119,10 @@ Database specific values (will use SQLite if not set): * `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`] + +Mail server specific values (will not send emails if not set): + +* ``SYNAPSE_SMTP_HOST``, hostname to the mail server. +* ``SYNAPSE_SMTP_PORT``, TCP port for accessing the mail server [default ``25``]. +* ``SYNAPSE_SMTP_USER``, username for authenticating against the mail server if any. +* ``SYNAPSE_SMTP_PASSWORD``, password for authenticating against the mail server if any. diff --git a/contrib/docker/conf/homeserver.yaml b/contrib/docker/conf/homeserver.yaml index 3b57f7174d..198b8ddee7 100644 --- a/contrib/docker/conf/homeserver.yaml +++ b/contrib/docker/conf/homeserver.yaml @@ -146,6 +146,7 @@ enable_registration: {{ "True" if SYNAPSE_ENABLE_REGISTRATION else "False" }} registration_shared_secret: "{{ SYNAPSE_REGISTRATION_SHARED_SECRET }}" bcrypt_rounds: 12 allow_guest_access: {{ "True" if SYNAPSE_ALLOW_GUEST else "False" }} +enable_group_creation: true # The list of identity servers trusted to verify third party # identifiers by this server. @@ -200,19 +201,19 @@ perspectives: password_config: enabled: true -#email: -# enable_notifs: false -# smtp_host: "localhost" -# smtp_port: 25 -# smtp_user: "exampleusername" -# smtp_pass: "examplepassword" -# require_transport_security: False -# notif_from: "Your Friendly %(app)s Home Server " -# app_name: Matrix -# template_dir: res/templates -# notif_template_html: notif_mail.html -# notif_template_text: notif_mail.txt -# notif_for_new_users: True -# riot_base_url: "http://localhost/riot" - -enable_group_creation: true +{% if SYNAPSE_SMTP_HOST %} +email: + enable_notifs: false + smtp_host: "{{ SYNAPSE_SMTP_HOST }}" + smtp_port: {{ SYNAPSE_SMTP_PORT or "25" }} + smtp_user: "{{ SYNAPSE_SMTP_USER }}" + smtp_pass: "{{ SYNAPSE_SMTP_PASSWORD }}" + require_transport_security: False + notif_from: "{{ SYNAPSE_SMTP_FROM or "hostmaster@" + SYNAPSE_SERVER_NAME }}" + app_name: Matrix + template_dir: res/templates + notif_template_html: notif_mail.html + notif_template_text: notif_mail.txt + notif_for_new_users: True + riot_base_url: "https://{{ SYNAPSE_SERVER_NAME }}" +{% endif %} -- cgit 1.4.1 From d8680c969bb2e8248436d7352ebf0f5cd1daea7b Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 21:55:35 +0100 Subject: Make it clear that the image has two modes of operation --- contrib/docker/README.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index b74c72698c..27e25afcef 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -21,23 +21,42 @@ You may have a local Python wheel cache available, in which case copy the releva ## Run +This image is designed to run either with an automatically generated configuration +file or with a custom configuration that requires manual edition. + +### Automated configuration + 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, including example labels for reverse proxying and other artifacts. -Then, to run the server: +Read the section about environment variables and set at least mandatory variables, +then run the server: ``` docker-compose up -d ``` -In the case you specify a custom path for you configuration file and wish to -generate a fresh ``homeserver.yaml``, simply run: +### Manual configuration + +A sample ``docker-compose.yml`` is provided, including example labels for +reverse proxying and other artifacts. + +Specify a ``SYNAPSE_CONFIG_PATH``, preferably to a persistent path, +to use manual configuration. To generate a fresh ``homeserver.yaml``, simply run: ``` docker-compose run --rm -e SYNAPSE_SERVER_NAME=my.matrix.host synapse generate ``` +Then, customize your configuration and run the server: + +``` +docker-compose up -d +``` + +### Without Compose + 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 @@ -49,10 +68,10 @@ docker run \ --name synapse \ -v ${DATA_PATH}:/data \ -e SYNAPSE_SERVER_NAME=my.matrix.host \ - matrixdotorg/synapse:latest + -e SYNAPSE_REPORT_STATS=yes \ + docker.io/matrixdotorg/synapse:latest ``` - ## Volumes The image expects a single volume, located at ``/data``, that will hold: -- cgit 1.4.1 From 48e2c641b80ac57d16701e4a27f348ea4f2c66cc Mon Sep 17 00:00:00 2001 From: kaiyou Date: Thu, 8 Feb 2018 21:58:12 +0100 Subject: Specify the Docker registry in the build tag --- contrib/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 27e25afcef..221d9c53b5 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -12,7 +12,7 @@ use that server. Build the docker image with the `docker build` command from the root of the synapse repository. ``` -docker build -t matrixdotorg/synapse . +docker build -t docker.io/matrixdotorg/synapse . ``` The `-t` option sets the image tag. Official images are tagged `matrixdotorg/synapse:` where `` is the same as the release tag in the synapse git repository. -- cgit 1.4.1 From e511979fe6c4a03da3e9c1d16672e263f54ee2d3 Mon Sep 17 00:00:00 2001 From: kaiyou Date: Fri, 9 Feb 2018 00:13:26 +0100 Subject: Make SYNAPSE_MACAROON_SECRET_KEY a mandatory option --- contrib/docker/README.md | 3 ++- contrib/docker/start.py | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 221d9c53b5..25c358c847 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -111,6 +111,8 @@ variables are available for configuration: * ``SYNAPSE_SERVER_NAME`` (mandatory), the current server public hostname. * ``SYNAPSE_REPORT_STATS``, (mandatory, ``yes`` or ``no``), enable anonymous statistics reporting back to the Matrix project which helps us to get funding. +* ``SYNAPSE_MACAROON_SECRET_KEY`` (mandatory) secret for signing access tokens + to the server, set this to a proper random key. * ``SYNAPSE_NO_TLS``, set this variable to disable TLS in Synapse (use this if you run your own TLS-capable reverse proxy). * ``SYNAPSE_ENABLE_REGISTRATION``, set this variable to enable registration on @@ -130,7 +132,6 @@ Shared secrets, that 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): diff --git a/contrib/docker/start.py b/contrib/docker/start.py index 32142bbe00..d4c1140b1d 100755 --- a/contrib/docker/start.py +++ b/contrib/docker/start.py @@ -44,8 +44,8 @@ else: if "SYNAPSE_CONFIG_PATH" in environ: args += ["--config-path", environ["SYNAPSE_CONFIG_PATH"]] else: - check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS")) - generate_secrets(environ, ("SYNAPSE_REGISTRATION_SHARED_SECRET", "SYNAPSE_MACAROON_SECRET_KEY")) + check_arguments(environ, ("SYNAPSE_SERVER_NAME", "SYNAPSE_REPORT_STATS", "SYNAPSE_MACAROON_SECRET_KEY")) + generate_secrets(environ, ("SYNAPSE_REGISTRATION_SHARED_SECRET",)) environ["SYNAPSE_APPSERVICES"] = glob.glob("/data/appservices/*.yaml") if not os.path.exists("/compiled"): os.mkdir("/compiled") convert("/conf/homeserver.yaml", "/compiled/homeserver.yaml", environ) -- cgit 1.4.1 From d4c14e143825c679a7909b009aec2e51f829857f Mon Sep 17 00:00:00 2001 From: kaiyou Date: Tue, 1 May 2018 20:47:58 +0200 Subject: Fix the documentation about 'POSTGRES_DB' --- contrib/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'contrib/docker/README.md') diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 25c358c847..aed56646c2 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -135,7 +135,7 @@ Shared secrets, that will be initialized to random values if not set: Database specific values (will use SQLite if not set): -* `POSTGRES_DATABASE` - The database name for the synapse postgres database. [default: `matrix`] +* `POSTGRES_DB` - 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: `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`] -- cgit 1.4.1