# xssbook to matrix bridge

references:
- [matrix-appservice-bridge howto](https://github.com/matrix-org/matrix-appservice-bridge/blob/develop/HOWTO.md)
- [the slack bridge](https://github.com/matrix-org/matrix-appservice-slack)

## usage

```sh
mkdir data # if it doesn't already exist
node . -r -u "http://url-to-appservice:8000" # the url here is how the homeserver will try to access the appservice, the port is your choice
```  
this generates a registration file `data/xss-registration.yaml` that you use to register the bridge with a matrix homeserver  
install the app service like [this](https://docs.mau.fi/bridges/general/registering-appservices.html)

then make a `data/xss.yaml` file:
```yaml
xssbook:
  url: http://localhost:8080 # url to xssbook instance
  bridge_username: bridge # name of the bridge user (used to poll for new posts)
  room: "!roomid:localhost" # matrix room to post to
matrix:
  homeserver_url: http://localhost:8008 # http(s) url to your homeserver
  homeserver: localhost # what appears in the second half of matrix IDs
```
and run
```sh
node . -p 8000 -c data/xss.yaml
# the port needs to be the same one from the previous node command, if bridging to matrix
```

that should be it.

## if you want to use docker instead

be aware of networking shenanigans, especially if you're running this on the same machine as the homeserver.

```sh
docker build -t matrixssbook . # make sure the image is built
mkdir data # you *may* need to chmod a+w data to allow the node user inside the container to write to the folder

docker run --rm -v $PWD/data:/appservice/data matrixssbook -r -u "http://url-to-appservice:8000"
```

create the `data/xss.yaml` as before

```sh
docker run -v $PWD/data:/appservice/data matrixssbook # note: the default cmd is `-p 8000 -c data/xss.yaml`, if you used a different port you'll need to include parameters here
```

## docker-compose

if you're running [synapse through docker-compose](https://github.com/matrix-org/synapse/blob/master/contrib/docker/docker-compose.yml), you can add this appservice to your `docker-compose.yaml` file:
```sh
docker build -t matrixssbook /path/to/this/repo # make sure the image is built
# run in the same folder as your docker-compose file
mkdir data # you *may* need to chmod a+w data to allow the node user inside the container to write to the folder
docker run --rm -v $PWD/data:/appservice/data matrixssbook -r -u "http://matrixssbook:8000" # this url can be used verbatim
```
create the `data/xss.yaml` file as before, but use `homeserver_url: http://synapse:8008`
then insert this snippet into your `docker-compose.yaml`
```yaml
# in synapse's volumes section, use this (optional, you can also just copy the file into synapse's data directory manually)
    - ./data/xss-registration.yaml:/data/xss-registration.yaml
# add a new service
matrixssbook:
  image: matrixssbook
  volumes:
    - ./data:/appservice/data
```
make sure to edit synapse's config to add
```yaml
app_service_config_files:
  - /data/xss-registration.yaml
```

## using with matrix

- make a new room, make sure `xss.room` in the bridge's config is set to the room's ID
- invite `@xssbook:homeserver`, it should automatically accept the invite
- start posting