diff --git a/changelog.d/16392.doc b/changelog.d/16392.doc new file mode 100644 index 0000000000..03c5665169 --- /dev/null +++ b/changelog.d/16392.doc @@ -0,0 +1 @@ +Make it easier and out-of-box to deploy with docker-compose. \ No newline at end of file diff --git a/contrib/docker/README.md b/contrib/docker/README.md index 89c1518bd0..8948d62d96 100644 --- a/contrib/docker/README.md +++ b/contrib/docker/README.md @@ -1,31 +1,48 @@ # Synapse Docker +There are two `docker-compose.yaml` files to support `sqlite` and `postgres` databases. + +1. The `postgres` database is recommended for production use, you could use `docker-compose.postgres.yaml`. + +2. The `sqlite` database is recommended for development and testing, you could use `docker-compose.sqlite.yaml`. + +Please comment/uncomment sections that are not suitable for your usecase. +Go to the directory `contrib/docker` to run the below command. + ### Configuration -A sample ``docker-compose.yml`` is provided, including example labels for -reverse proxying and other artifacts. The docker-compose file is an example, -please comment/uncomment sections that are not suitable for your usecase. - -Specify a ``SYNAPSE_CONFIG_PATH``, preferably to a persistent path, -to use manual configuration. - -To generate a fresh `homeserver.yaml`, you can use the `generate` command. +The container `synapse-init` is to generate a fresh `homeserver.yaml`, you can use the `generate` command. (See the [documentation](../../docker/README.md#generating-a-configuration-file) for more information.) You will need to specify appropriate values for at least the `SYNAPSE_SERVER_NAME` and `SYNAPSE_REPORT_STATS` environment variables. For example: -``` -docker-compose run --rm -e SYNAPSE_SERVER_NAME=my.matrix.host -e SYNAPSE_REPORT_STATS=yes synapse generate -``` +Specify a ``SYNAPSE_CONFIG_PATH``, preferably to a persistent path, +to use manual configuration. -(This will also generate necessary signing keys.) +You just choose one of the following options. -Then, customize your configuration and run the server: +#### sqlite -``` -docker-compose up -d -``` +1. change the `SYNAPSE_SERVER_NAME` of `synapse-init` at the `docker-compose.sqlite.yaml` +2. change the local device path of `volumes` at the `docker-compose.sqlite.yaml` +3. run the command `docker-compose -f docker-compose.sqlite.yml up -d` + +#### postgres + +1. change the `SYNAPSE_SERVER_NAME` of `synapse-init` at the `docker-compose.postgres.yaml` +2. change the local device path of `volumes` for `synapse_data` and `pg_data` at the `docker-compose.postgres.yaml` +3. create the direcotry of `pg_data`, such as `mkdir -p pg_data` +3. change the postgres password by `POSTGRES_PASSWORD` +3. run the command `docker-compose -f docker-compose.postgres.yml up -d` + +### Validate + +Open `http://localhost:8008` in your browser, and it's successful if you see the welcome page. + +## Next + +Set up a reverse proxy to expose the port and host the tls certificates. See [reverse proxy](https://matrix-org.github.io/synapse/latest/reverse_proxy.html) ### More information diff --git a/contrib/docker/deploy_data/.gitkeep b/contrib/docker/deploy_data/.gitkeep new file mode 100644 index 0000000000..e69de29bb2 diff --git a/contrib/docker/docker-compose.postgres.yml b/contrib/docker/docker-compose.postgres.yml new file mode 100644 index 0000000000..4f150da07e --- /dev/null +++ b/contrib/docker/docker-compose.postgres.yml @@ -0,0 +1,93 @@ +# This compose file is compatible with Compose itself, it might need some +# adjustments to run properly with stack. + +version: '3' + +x-pg-env: &pg_env + POSTGRES_USER: synapse + POSTGRES_PASSWORD: changeme + POSTGRES_DB: synapse + +services: + + # use this container to generate the config file and then exit + synapse-init: + image: matrixdotorg/synapse:latest + container_name: synapse-init + entrypoint: 'bash' + command: "-c './start.py generate && ./start.py migrate_config'" + volumes: + - synapse_data:/data + environment: + # more environment variables are available in the project directory `./docker/conf/homeserver.yaml` + SYNAPSE_SERVER_NAME: 'changeme.com' # change to your server name + SYNAPSE_REPORT_STATS: 'yes' + SYNAPSE_NO_TLS: 'yes' + POSTGRES_HOST: 'db' + <<: *pg_env + depends_on: + db: + condition: service_healthy + + synapse: + image: matrixdotorg/synapse:latest + # Since synapse does not retry to connect to the database, restart upon + # failure + restart: unless-stopped + # See the readme for a full documentation of the environment settings + # NOTE: You must edit homeserver.yaml to use postgres, it defaults to sqlite + environment: + - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml + volumes: + # You may either store all the files in a local folder + - synapse_data:/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: + condition: service_healthy + synapse-init: + # more information about condition https://github.com/compose-spec/compose-spec/blob/master/05-services.md#long-syntax-1 + condition: service_completed_successfully + ports: + # http port, you could use `8448` if you unset `SYNAPSE_NO_TLS` above the `synapse-init` container + - 8008:8008/tcp + + db: + image: docker.io/postgres:12-alpine + # Change that password, of course! + environment: + # ensure the database gets created correctly + # https://matrix-org.github.io/synapse/latest/postgres.html#set-up-database + POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C + <<: *pg_env + volumes: + # You may store the database tables in a local folder.. + - pg_data:/var/lib/postgresql/data + # .. or store them on some high performance storage for better results + # - /path/to/ssd/storage:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready", "-d", "synapse"] + interval: 30s + timeout: 60s + retries: 5 + start_period: 80s + +volumes: + synapse_data: + # you need to set the local path to your data directory here or you would lost the data if you clean the volume + driver: local + driver_opts: + type: 'none' + o: 'bind' + device: '${PWD}/deploy_data' # change the `device` to your local path + + pg_data: + # you need to set the local path to your data directory here or you would lost the data if you clean the volume + driver: local + driver_opts: + type: 'none' + o: 'bind' + device: '${PWD}/pg_data' # change the `device` to your local path \ No newline at end of file diff --git a/contrib/docker/docker-compose.sqlite.yml b/contrib/docker/docker-compose.sqlite.yml new file mode 100644 index 0000000000..172a626385 --- /dev/null +++ b/contrib/docker/docker-compose.sqlite.yml @@ -0,0 +1,56 @@ +# This compose file is compatible with Compose itself, it might need some +# adjustments to run properly with stack. + +version: '3' + +services: + + # use this container to generate the config file and then exit + synapse-init: + image: matrixdotorg/synapse:latest + container_name: synapse-init + entrypoint: 'bash' + command: "-c './start.py generate && ./start.py migrate_config'" + volumes: + - synapse_data:/data + environment: + # more environment variables are available in the project directory `./docker/conf/homeserver.yaml` + SYNAPSE_SERVER_NAME: 'changeme.com' # change to your server name + SYNAPSE_REPORT_STATS: 'yes' + SYNAPSE_NO_TLS: 'yes' + + synapse: + image: matrixdotorg/synapse:latest + container_name: synapse + # Since synapse does not retry to connect to the database, restart upon + # failure + restart: unless-stopped + # See the readme for a full documentation of the environment settings + # NOTE: You must edit homeserver.yaml to use postgres, it defaults to sqlite + environment: + - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml + volumes: + # You may either store all the files in a local folder + - synapse_data:/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: + synapse-init: + # more information about condition https://github.com/compose-spec/compose-spec/blob/master/05-services.md#long-syntax-1 + condition: service_completed_successfully + # In order to expose Synapse, you could use reverse proxying, + # or you could expose the ports directly. + ports: + # http port, you could use `8448` if you unset `SYNAPSE_NO_TLS` above the `synapse-init` container + - 8008:8008/tcp + +volumes: + synapse_data: + # you need to set the local path to your data directory here or you would lost the data if you clean the volume + driver: local + driver_opts: + type: 'none' + o: 'bind' + device: '${PWD}/deploy_data' # change the `device` to your local path \ No newline at end of file diff --git a/contrib/docker/docker-compose.yml b/contrib/docker/docker-compose.yml deleted file mode 100644 index 5ac41139e3..0000000000 --- a/contrib/docker/docker-compose.yml +++ /dev/null @@ -1,66 +0,0 @@ -# This compose file is compatible with Compose itself, it might need some -# adjustments to run properly with stack. - -version: '3' - -services: - - synapse: - build: - context: ../.. - dockerfile: docker/Dockerfile - image: docker.io/matrixdotorg/synapse:latest - # Since synapse does not retry to connect to the database, restart upon - # failure - restart: unless-stopped - # See the readme for a full documentation of the environment settings - # NOTE: You must edit homeserver.yaml to use postgres, it defaults to sqlite - environment: - - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml - 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 - # instance expose the TLS port directly: - ports: - - 8448:8448/tcp - # ... or use a reverse proxy, here is an example for traefik: - labels: - # The following lines are valid for Traefik version 1.x: - - traefik.enable=true - - traefik.frontend.rule=Host:my.matrix.Host - - traefik.port=8008 - # Alternatively, for Traefik version 2.0: - - traefik.enable=true - - traefik.http.routers.http-synapse.entryPoints=http - - traefik.http.routers.http-synapse.rule=Host(`my.matrix.host`) - - traefik.http.middlewares.https_redirect.redirectscheme.scheme=https - - traefik.http.middlewares.https_redirect.redirectscheme.permanent=true - - traefik.http.routers.http-synapse.middlewares=https_redirect - - traefik.http.routers.https-synapse.entryPoints=https - - traefik.http.routers.https-synapse.rule=Host(`my.matrix.host`) - - traefik.http.routers.https-synapse.service=synapse - - traefik.http.routers.https-synapse.tls=true - - traefik.http.services.synapse.loadbalancer.server.port=8008 - - traefik.http.routers.https-synapse.tls.certResolver=le-ssl - - db: - image: docker.io/postgres:12-alpine - # Change that password, of course! - environment: - - POSTGRES_USER=synapse - - POSTGRES_PASSWORD=changeme - # ensure the database gets created correctly - # https://matrix-org.github.io/synapse/latest/postgres.html#set-up-database - - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C - 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/postgresql/data