matrixssbook/README.md

xssbook to matrix bridge

references:

• matrix-appservice-bridge howto
• the slack bridge

usage

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

then make a data/xss.yaml file:

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

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.

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

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, you can add this appservice to your docker-compose.yaml file:

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

# 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

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