diff --git a/README.md b/README.md index c97451b..abab4be 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,17 @@ # matrix-sip-bridge A bridge between [Matrix](https://matrix.org/) and VoIP via [SIP](https://en.wikipedia.org/wiki/Session_Initiation_Protocol) to answer (and in future make) phone calls from Matrix. -| :exclamation: Documentation will follow shortly | -|:--| +## Please be aware, that this is considered **early stage software** +There may or may not be a lot of bugs and breaking changes. +But *especially* because of this, you will be able to influence how this project continues to develop. + +Feel free to [file issues](https://github.com/IndeedNotJames/matrix-sip-bridge/issues/new), ask questions, provide feedback, [hang out in the official matrix room](#matrix-room) or contribute some code - or whatever! šŸ˜Š + +## Documentation +Documentation can be found in [`./docs`](https://github.com/IndeedNotJames/matrix-sip-bridge/tree/main/docs) +If you'd like to improve those, feel free to file a pull request or [let us know](#matrix-room) where some things were unclear to you. + +## Matrix Room +Feel free to ask questions, provide feedback or just hang out in the official Matrix room: + +[#matrix-sip-bridge:indeednotjames.com](https://matrix.to/#/#matrix-sip-bridge:indeednotjames.com) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7a67dbc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,59 @@ +# matrix-sip-bridge documentation + +The current documentation is somewhat suboptimal and there are many things to improve. +If you need any help, feel free to ask any questions in the [matrix room](https://github.com/IndeedNotJames/matrix-sip-bridge/blob/main/README.md#matrix-room) + +## Install +As of now, the installation is pretty Docker centric, but it should be fine to just use `npm install`/`yarn install` with a *systemd* or *openrc* service. +It will improve in the futureā„¢ + +### Docker +How to install Docker is likely out of the scope of this document. Follow the [official Docker install](https://docs.docker.com/engine/install/) steps if you haven't already. Podman should in theory work just fine too. + +The official container image is available both at https://github.com/indeednotjames/matrix-sip-bridge/pkgs/container/matrix-sip-bridge and https://hub.docker.com/r/indeednotjames/matrix-sip-bridge + +#### Supported Docker tags +* `latest` is the latest stable release +* `x.y.z` is a specific `x.y.z` release (e.g. `:0.1.0`) +* `x.y` is a specific `x.y.*` release (e.g. `:0.1` would point `:0.1.0` or `:0.1.1`) +* `edge` is always the latest commit (unstable, "living on the edge") +* `sha-*` allows you to run a specific commit + +At the time of writing, you have to use the `:edge` that, because there hasn't been a release yet: +- `ghcr.io/indeednotjames/matrix-sip-bridge:edge` or +- `indeednotjames/matrix-sip-bridge:edge` (`docker.io/indeednotjames/matrix-sip-bridge:edge`) + +**An example [`docker-compose.yml`](https://github.com/IndeedNotJames/matrix-sip-bridge/blob/main/docker-compose.yml) is available to use at the projects root.** + +Alternatively, you can build a huge `docker run` command like so: +See [Configure](#configure) for all required options. + +```bash +āÆ docker run \ + --restart=always \ + --name=matrix-sip-bridge \ + --env="MX_HOMESERVER=https://homeserver.example" \ + --env="MX_ACCESSTOKEN=See 'Configure' below" \ + --env="MX_USERID=@localpart:homeserver.example" \ + --env="MX_ROOMID=!roomId:homeserver.example" \ + --env="SIP_SERVER=wss://sip.sipgate.de" \ + --env="SIP_URI=sip:userAddress@sipgate.de" \ + --env="SIP_USER=your userAddress" \ + --env="SIP_PASSWORD=your sip user password" \ + ghcr.io/indeednotjames/matrix-sip-bridge:edge +``` + +## Configure +As of now, everything gets configured via environment variables and there is no persistent data volume needed. +However, there is a pretty high chance this will later down the road. + +All those environment variables are listed in the [`.env-example` file](https://github.com/IndeedNotJames/matrix-sip-bridge/blob/main/.env-example). +In detail explanations will follow eventually. + +### SIP +Your SIP server requires websocket support for now. + +For example *sipgate.de* provides `wss://sip.sipgate.de` for you to use. + +### Obtaining an access token +Follow https://t2bot.io/docs/access_tokens/ for way to get your bot account's access token via Element.