matrix-synapse/README.md

# Matrix (Synapse)

<!-- metadata -->

* **Category**: Apps
* **Status**: 0, work-in-progress
* **Image**: [`matrixdotorg/synapse`](https://hub.docker.com/r/matrixdotorg/synapse), 4, upstream
* **Healthcheck**: Yes
* **Backups**: No
* **Email**: Yes
* **Tests**: No
* **SSO**: Yes

<!-- endmetadata -->

## Basic usage

1. Set up Docker Swarm and [`abra`](https://docs.coopcloud.tech/abra/)
2. Deploy [`coop-cloud/traefik`](https://git.coopcloud.tech/coop-cloud/traefik)
3. `abra app new matrix-synapse --secrets` (optionally with `--pass` if you'd like to save secrets in `pass`)
4. `abra app YOURAPPDOMAIN config` - be sure to change `$DOMAIN` to something that resolves to your Docker swarm box
5. `abra app YOURAPPDOMAIN deploy`
6. Create an initial user: `abra app YOURAPPDOMAIN run app register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008`

## Tips & Tricks

### Disabling federation

> We're not sure this does it exactly and there is still a discussion running
> upstream about whether this is the right way to do it & whether it could be
> more convenient. We welcome issues / change sets to close up more federation
> functionality.

- use `DISABLE_FEDERATION=1` to turn off federation listeners
- don't use [`compose.matrix.yml`](https://git.coopcloud.tech/coop-cloud/traefik/src/branch/master/compose.matrix.yml) in your traefik config to keep the federation ports closed

### Enabling federation

See [`#27`](https://git.coopcloud.tech/coop-cloud/matrix-synapse/pulls/27) for more.

Depending on your setup, using `SERVE_SERVER_WELLKNOWN=true` might work to start federating.

Make sure you don't leave `DISABLE_FEDERATION=1` set!

### Seeing what changed in `homeserver.yaml` between versions

Change the version range to suit your needs.

```
git clone https://github.com/matrix-org/synapse
cd synapse/docs
git log --follow -p v1.48.0..v1.51.0 sample_config.yaml
```

### Generating a new `homeserver.yaml`

The default is also available to see [here](https://matrix-org.github.io/synapse/latest/usage/configuration/homeserver_sample_config.html).

```
docker run -it \
  --entrypoint="" \
  -e SYNAPSE_SERVER_NAME=foo.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:v1.48.0 \
  sh -c '/start.py generate; cat /data/homeserver.yaml' > homeserver.yaml.tmpl`
```

### Generating a new `<server>.log.config`

```
docker run -it \
  --entrypoint="" \
  -e SYNAPSE_SERVER_NAME=foo.com \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:v1.48.0 \
  sh -c '/start.py generate; cat /data/foo.com.log.config' > log.config
```

### Getting client discovery on a custom domain

You'll need to deploy something like [this](https://git.autonomic.zone/ruangrupa/well-known-uris).

This could be implemented in this recipe but we haven't merged it in yet. Change sets are welcome.

### Telegram bridging

> WIP

Setting it up is a bit of a chicken/egg & chasing cats moment.

You need to get your bot setup on the telegram side first and have these values:

```
api_id: ...
api_hash: ...
telegram_bot_token: ...
```

Here is a rough guide:

```
abra app secret insert <domain> telegram_api_hash v1 <secret>
abra app secret insert <domain> telegram_bot_token v1 <secret>
abra app secret generate -a <domain>

abra app deploy <domain>
abra app run matrix.fva.wtf telegram_bridge cat /data/registration.yaml
abra app undeploy <domain>

abra app secret rm <domain> telegram_as_token
abra app secret insert <domain> telegram_as_token v1 <secret>

abra app secret rm <domain> telegram_as_token
abra app secret insert <domain> telegram_hs_token v1 <secret>

abra app deploy <domain>
```

Some helpful documentation:

- [`docs.mau.fi`](https://docs.mau.fi/bridges/python/setup/docker.html?bridge=telegram)
- [`example-config.yaml`](https://mau.dev/mautrix/telegram/-/blob/master/mautrix_telegram/example-config.yaml)

### Discord bridging

> WIP

Just as messy as the Telegram bridging above! Rough guide:

- get a local copy of [`config.yaml`](https://github.com/matrix-org/matrix-appservice-discord/blob/develop/config/config.sample.yaml)
- fill it out with the values you need, all the discord token stuff, etc.
- run `mkdir -p data && cp config.yaml data/` then `docker run --rm -v data:/data halfshot/matrix-appservice-discord:v1.0.0 sh -c "cd /data && node /build/src/discordas.js -r -u "http://discordbridge:9005" -c config.yaml"`
- this generates the app service registration configuration you need to feed to the homeserver
- run secret generation for the `discord_db_password`, insert your `discord_bot_token`
- run `abra app cp <domain> discord-registration.yaml app:/discord-data` (it has to be called `discord-registration.yaml`)
- deploy the bridge & happy hacking

Some helpful documentation:

- [`matrix-org/matrix-appservice-discord` docs](https://github.com/matrix-org/matrix-appservice-discord#bridging-a-room)
- [`t2bot.io/discord`](https://t2bot.io/discord/)