README.md

Gischat - API

---

Gischat API backend for chatting with your tribe in GIS tools like QGIS (using QTribu plugin available from official plugin repository), QField and other to come

No database : messages are not stored. Just stateless websockets.

Known instances

Following instances are up and running :

URL	Description	Location
https://gischat.geotribu.net	"official" international instance	Germany
https://gischat.geotribu.fr	"official" french-speaking instance	Germany

Developer information

• Rooms can be fetched using the /rooms endpoint
• Rules can be fetched using the /rules endpoint
• Number of connected users can be fetched using the /status endpoint
• New users must connect a websocket to the /room/{room_name}/ws endpoint
• Messages passing through the websocket are simple JSON dicts like this: {"message": "hello", "author": "Hans Hibbel", "avatar": "mGeoPackage.svg"}
• ⚠️ Messages having the "internal" author are internal messages and should not be printed, they contain technical information: {"author": "internal", "nb_users": 36}
• "author" value must be alphanumeric (or _ or -) and have min / max length set by MIN_AUTHOR_LENGTH / MAX_AUTHOR_LENGTH environment variables
• "message" value must have max length set by MAX_MESSAGE_LENGTH environment variable

Deploy a self-hosted instance

Setup Gischat backend

• Install docker using the official documentation

• Create a docker-compose.yaml file on your server :

services:
  api:
    image: gounux/gischat:latest
    container_name: gischat-app
    environment:
      - ROOMS=QGIS,Field and mobile,GIS tribe, Living room,Kitchen,Garden
      - RULES=Be kind and nice to this wonderful world
      - MAIN_LANGUAGE=en
      - ENVIRONMENT=production
      - MIN_AUTHOR_LENGTH=3
      - MAX_AUTHOR_LENGTH=32
      - MAX_MESSAGE_LENGTH=255
    ports:
      - 8000:8000
    restart: unless-stopped

ROOMS environment variable is a comma-separated list of strings which represent the available chat rooms
RULES environment variable describes the instance's rules

• Launch the app using compose :

docker compose up -d

• Have a look at the logs :

docker compose logs -f

Run behind a nginx proxy using HTTPS

• Install nginx and certbot

apt install nginx certbot

• Get a Let's Encrypt SSL certificate for your domain :

# stop nginx service
systemctl stop nginx
# get the certificate
certbot certonly --standalone -d DOMAIN
# restart nginx service
systemctl start nginx

The Let's Encrypt SSL certificate should be saved to /etc/letsencrypt/live/DOMAIN

• Create a nginx config file :

touch /etc/nginx/sites-available/gischat.conf

• Edit the file and add the following content (using your domain):

upstream gischat_upstream {
  server 127.0.0.1:8000;
}

server {
  listen 80;
  server_name <DOMAIN>;
  return 301 https://$host$request_uri;
}

server {

  listen 443 ssl;
  server_name <DOMAIN>;

  ssl_certificate /etc/letsencrypt/live/<DOMAIN>/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/<DOMAIN>/privkey.pem;

  location / {
    proxy_pass http://gischat_upstream;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
  }
}

• Create a symlink to enable the nginx config file :

ln -s /etc/nginx/sites-available/gischat.conf /etc/nginx/sites-enabled/gischat.conf

• Check that the nginx config file is okey :

nginx -t

You should see something like this :

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

• Reload nginx configuration

systemctl reload nginx

That's it, you should be able to chat now with your fellow GIS mates !

Development

• Install poetry:

python -m pip install poetry

• Install project's dependencies using poetry:

poetry install

• Install pre-commit tools:

poetry run pre-commit install

• Create local environment file and edit it:

cp .env.example .env

• Launch API:

poetry run uvicorn gischat.app:app --reload --env-file .env --log-config=log_config.yaml

Build

• Build docker image:

docker build . --tag geotribu/gischat:latest

• Run docker image:

docker run geotribu/gischat:latest --env ROOMS=QGIS,QField,Geotribu --env RULES="Those are the rules: ..."