wicrs_server 0.9.2

A server/channel based chat handler backend.
Documentation

WICRS Server

crates.io docs.rs Discord Matrix

A server for handling chat rooms and messaging groups written in rust.

Build

Install Rust by following these instructions. Then clone the git repo, then to build:

git clone https://github.com/wicrs/server.git wicrs_server
cd wicrs_server
cargo build # to build the release version run cargo build --release

Setup

First you need to create a GitHub OAuth application by following the instructions here, make sure to set the callback URL to $HOSTNAME:$PORT/api/v2/auth/github, replace $PORT with the port you choose in the config and replace $HOSTNAME with the address you will navigate to when accessing the WICRS API.

To run the server you first need to create a config file named config.json in the server's working directory, which should be reserved for the server. Here is an example of what the contents of config.json should be:

{
    "auth_services": {
        "github": {
            "enabled": true,
            "client_id": "$GITHUB_CLIENT_ID",
            "client_secret": "$GITHUB_CLIENT_SECRET"
        }
    },
    "show_version": true,
    "ws_client_timeout": 10000,
    "ws_hb_interval": 1000,
    "tantivy_commit_threshold": 10000
}

Make sure to replace $GITHUB_CLIENT_ID with the client ID and $GITHUB_CLIENT_SECRET with the client secret you got when you created the GitHub OAuth application. address should be set to the local address you want the server to listen on, for example you can use 127.0.0.1:8080. The show_version variable determines whether or not the server will tell clients it's version when they go to the HTTP root (/). The ws_client_timeout configuration option determines how long (in milliseconds) to wait before a client using websockets should be disconnected after their last hearbeat ping. The ws_hb_interval configuration option determines the interval between heartbeat pings sent to the client in milliseconds.

Note that the server application needs to be able to read ./config.json and must be able to read and write to ./data or most if not all requests will fail.

Once this is done run the server by executing cargo run or cargo run --release if you are in the project git directory. If you are not in the project's git directory you will need to either put the executable in the desired run directory (where you have the config.json file) and run ./wicrs_server. Otherwise you need to have it in your path in which case you just need to run wicrs_server in your chosen run directory.

Developing and Contributing

To contribute fork the GitHub repo and make your changes, for changes to be accepted your fork must pass all of the tests, to run the tests go to the root directory of the project and run cargo test. If you add any features make sure to add tests to ensure they work, it is also important that you add documentation for any features you add and explain what they are for, if your PR addresses an issue, you probably do not need to explain your changes. Another important thing is that you cannot use unstable (nightly) features when contributing to this repo.

Versioning

This project adheres to Semantic Versioning. However until 1.0.0 comes there will be the following rules:

  • Any API/ABI breaking changes will be notified in the changelog explicitly and results in minor version bumping.
  • API extending features results in patch version bumping.
  • Non-breaking bug fixes and performance improving results in patch version bumping.