deathangel908/pychat repository overview

⁠Live demo: pychat.org⁠, video⁠

⁠Table of contents

• About⁠
• When should I use pychat⁠
• How to host pychat⁠
  • Run test docker image⁠
  • Run prod docker image⁠
  • Native setup⁠
  • Frontend⁠
  • Desktop app⁠
  • Android app⁠
• Development setup⁠
  • Install OS packages⁠
  • Bootstrap files:⁠
  • Build frontend⁠
  • Configure IDEs if you use it:⁠
  • Linting⁠
  • Start services and run:⁠
• Contribution guide⁠
  • Description⁠
  • Shell helper⁠
  • Frontend logging⁠
  • Icons⁠
  • Sustaining online protocol⁠
  • Database migrations⁠
  • Screen sharing for Chrome v71 or less⁠
  • WebRTC connection establishment⁠
  • Frontend Stack⁠
  • Frontend config⁠
• Github actions⁠
• TODO⁠

⁠About

Pychat is an opensource absolutely free communcation tool targeted for a copmany use. It's created as alternative to Slack/Discord. See the table below to understand its key features.

⁠When should I use pychat

I would personally use discord or slack as a company chat. They are built and maintained by thousands of people rather than a single person. BUT wait!!! There're some key factors of picking pychat over others:

1. Being opensource. If you need to add some custom tool or feature, you will never able to do this with any other messanger. Slack and discord provides plugins but they are still limited.
2. Being absolutely free. You don't need to pay anything to use or setup pychat at all. You can host pychat on low-end hardware like Raspberry Pi which costs under 50$ and will easily handle thousands of active users. Slack and Discord will charge you⁠ for the set of features you need now or WILL need in the future. Telegram/Skype/Viber and etc are not corporate chats and they lack a lot of features and there're people all over the world which could accidentaly be invited to your group.
3. Security. All of the chats above are SAAS solutions, but not Pychat! Remember wHen you chose any messangers, all of your communication is stored on external hard drive which is always less secure. Some messangers like viber or whatsapp backup do not store messages but rather backup history to your google driver. But that often leads to holes in history and broken search. Also only pychat features p2p file sharing. Do you still use messangers to echange ssh keys or any other secure files? Never store them on the server! Only with pychat you can send file directly to another person ommiting persisting it on the server.
4. You just feel enthusiastic for bleeding-edge opensource projects.

⁠How to host pychat

⁠Run test docker image

Please don't use this build for production, as it uses debug ssl certificate, lacks a few features and all files are located inside of container, meaning you will lose all data on container destroy.

• Download and run image:

docker run -tp 443:443 deathangel908/pychat-test

• Open https://localhost⁠

⁠Run prod docker image

Please run each step very carefully. Do not skip editing files, reading comments or any instructions. This may lead to bugs in the future.

• Ssl is required for webrtc (to make calls) and secure connection. Put your ssl certificates in the current directory: server.key and certificate.crt. If you don't own a domain you can create self-signed certificates with command below, with self-signed certificate browser will warn users with broken ssl.

openssl req -nodes -new -x509 -keyout server.key -out certificate.crt -days 3650

• Download settings.py⁠ and edit it according comments in it.
• Download production.json⁠ and edit it according wiki⁠
• Download turnserver.conf⁠ Replace server-name and realm to your domain.
• Create volume and copy files there

docker volume create pychat_data
containerid=`docker container create --name dummy -v pychat_data:/data hello-world`
docker cp settings.py dummy:/data/settings.py
docker cp production.json dummy:/data/production.json
docker cp turnserver.conf dummy:/data/turnserver.conf
docker cp certificate.crt dummy:/data/certificate.crt
docker cp server.key dummy:/data/server.key
docker rm dummy

If you need to edit files inside container you can use

docker run -i -t -v pychat_data:/tmp -it alpine /bin/sh

• Run image with:

docker run -t -v pychat_data:/data -p 443:443 -p 3478:3478 deathangel908/pychat

• Open https://localhost⁠ and enjoy it!

⁠Native setup

If you don't or unable to run docker you can alway do the setup w/o it. You definitely spend more time, so I would recommend to use docker if possible. But if you're still sure, here's the setup for cent-os/archlinux based system:

1. For production I would recommend to clone repository to /srv/http/pychat. If you want to close the project into a different directory, replace all absolute paths in config files. You can use download_content.sh rename_root_directory to do that.
2. Install packages:
   • For archlinux follow Install OS packages⁠, add add these ones: pacman -S postfix gcc jansson.
   • For centos use add alias yum="python2 $(which yum)" to /etc/bashrc if you use python3. And then install that packages yum install python34u, python34u-pip, redis, mysql-server, mysql-devel, postfix, mailx
   • If you use another OS, try to figure out from Install OS packages⁠ guide which things you need
3. If you want to use native file-uploader (nginx_upload_module written in C) instead of python uploader (which is a lot slower) you should build nginx yourself. For archlinux setup requires pacman -S python-lxml gd make geoip. To build nginx with this module run from the root user: bash download_content.sh build_nginx 1.15.3 2.3.0. And create dir + user useradd nginx; install -d -m 0500 -o http -g http /var/cache/nginx/. If you don't, just install nginx with your package manager: e.g. pacman -S nginx or yum install nginx on centos
4. Follow Bootstrap files⁠ flow.
5. I preconfigued native setup for domain pychat.org, you want to replace all occurrences of pychat.org in rootfs⁠ directory for your domain. To simplify replacing use my script: ./download_content.sh rename_domain your.new.domain.com. Also check rootfs/etc/nginx/sites-enabled/pychat.conf if server_name section is correct after renaming.
6. HTTPS is required for webrtc calls so you need to enable ssl:

• Either create your certificates e.g. openssl req -nodes -new -x509 -keyout server.key -out certificate.crt -days 3650
• Either use something like certbot⁠
• Either you already have certificates or already know how to do it.

1. Open /etc/nginx/sites-enabled/pychat.conf and modify it by:

• change server_name to one matching your domain/ip address
• remove check for host below it, if you're using ip
• change ssl_certificate and ssl_certificate_key path to ones that you generated
• if you didn't compile nginx with upload_file module, remove locations api/upload_file and @upload_file, otherwise leave it as it is.

1. Change to parent directory (which contains frontend and backend) and Copy config files to rootfs with from root user sh download_content.sh copy_root_fs.
2. Create a directory mkdir backend/downloading_photos in the backend directory and give it access chmod 777 downloading_photos cDon't forget to change the owner of current (project) directory to http user: chown -R http:http. And reload systemd config systemctl daemon-reload. Also you
3. Follow the Frontend⁠ steps
4. Generate postfix files: install -d -m 0555 -o postfix -g postfix /etc/postfix/virtual; postmap /etc/postfix/virtual; newaliases; touch /etc/postfix/virtual-regexp; echo 'root postmaster' > /etc/aliases
5. Start services:

• For archlinux/ubuntu: packages=( mysqld redis tornado@8888 nginx postfix ) ; for package in "${packages[@]}" ; do systemctl enable $package; done;. Service mysqld could be named mysql on Ubuntu.
• For centos: packages=( redis-server nginx postfix mysqld tornado@8888) ; for package in "${packages[@]}" ; do service $package start; done;

1. You can also enable autostart (after reboot)

• For archlinux/ubuntu: packages=( redis nginx postfix mysqld tornado) ; for package in "${packages[@]}" ; do systemctl start $package; done;
• For centos: chkconfig mysqld on; chkconfig on; chkconfig tornado on; chkconfig redis on; chkconfig postfix on

1. Open in browser https://your.domain.com⁠. Note that by default nginx accepts request by domain.name rather than ip.
2. If something doesn't work you want to check logs:

• Check logs in pychat/backend/logs directory.
• Check daemon logs: e.g. on Archlinux sudo journalctl -u YOUR_SERVICE. Where YOUR_SERVICE could be: nginx, mysql, tornado
• Check that user http has access to you project directory, and all directories inside, especially to /photos

⁠Frontend

• cd frontend; nvm install; nvm use.
• yarn install --frozen-lockfile
• Create production.json based on Frontend config⁠. Also you can use and modify cp docker/pychat.org/production.json ./frontend/
• Run yarn run prod. This generates static files in frotnend/dist directory.

⁠Desktop app

Pychat uses websql and built the way so it renders everything possible w/o network. You have 3 options:

⁠PWA

This is the simplest one. Just open settings page from you user and click "Add to home screen". Note that PWA is only available from chrome and chrome android. No support for IOS and other browsers. But PWA is the most stable from ones below.

⁠Natifier

Use nativifier⁠ to create a client (replace pychat.org for your server): npx run nativifier pychat.org

⁠Electron

• Create production.json based on Frontend config⁠
• Run cd frontend; yarn run electronProd.

⁠Android app

You can use PWA as it's described in desktop app section which I recommend. Other way is cordova which is a lot harder. If you're not familiar with android SDK I would recommend doing the steps below from AndroidStudio:

• Install android sdk, android platform tools. accept license
• Create production.json based on Frontend config⁠
• production.json "PUBLIC_PATH": "./", "BACKEND_ADDRESS": "pychat.org" build into dist, rm .gz. , copy to www. In index.html include <script src="cordova.js"></script>
• bash download_content.sh android

Example for mac:

1. Download oracle jdk-8
2. Install android studio
3. Run android studio that will install Android sdk for you
4. Accept licence with ~/Library/Android/sdk/tools/bin/sdkmanager --licenses
5. Install gradle⁠. brew install gradle
6. Open frontend/platforms/android with androidStudio
7. Start android emulator / connect device
8. put index.html into www
9. Run dev server with yarn run dev; bash download_content.sh android
10. TO debug java files you can run it directory from android studio. Debug button should be available out of the box after openning a project
11. To debug js you can open chrome://inspect/#devices in chrome
12. For any question check cordova docs⁠

⁠Development setup

The flow is the following

• Install OS packages depending on your OS type
• Bootstrap files
• Build frontend
• Start services and check if it works

⁠Install OS packages

This section depends on the OS you use. I tested full install on Windows/Ubuntu/CentOs/MacOS/Archlinux/Archlinux(rpi3 armv7). pychat.org⁠ currently runs on Archlinux Raspberry Pi 3.

⁠Windows⁠:

1. Install python⁠ with pip. only Python 3.6+ is required
2. Add pip and python to PATH variable.
3. Install redis⁠. Get the newest version or at least 2.8.
4. Install mysql⁠. You basically need mysql server and python connector.
5. You also need to install python's mysqlclient. If you want to compile one yourself you need to vs2015 tools. You can download visual-studio⁠ and install Common Tools for Visual C++ 2015⁠. You need to run setup as administrator. The only connector can be found here⁠. The wheel (already compiled) connectors can be also found here Mysqlclient⁠. Use pip to install them.
6. Add bash commands to PATH variable. Cygwin or git's will do find.(for example if you use only git PATH=C:\Program Files\Git\usr\bin;C:\Program Files\Git\bin).
7. Install nvm⁠.

⁠Ubuntu⁠:

1. Install required packages: apt-get install python pip mysql-server libmysqlclient-dev (python should be 3.6-3.8) If pip is missing check python-pip. For old versions of Ubuntu you can use this ppa: sudo add-apt-repository ppa:deadsnakes/ppa; sudo apt-get update; sudo apt-get install python3.8 python3.8-dev python3.8-venv python3.8-apt; curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py; python3.8 get-pip.py
2. Install redis database: add-apt-repository -y ppa:rwky/redis; apt-get install -y redis-server
3. Install mysqlclient pip install mysqlclient==1.3.13
4. Install nvm⁠

⁠Archlinux⁠:

1. Install system packages: pacman -S unzip python python-pip redis yarn mariadb python-mysqlclient. nvm is located in aur⁠ so yay -S nvm (or use another aur package)
2. If you just installed mariadb you need to initialize it: mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql.

⁠MacOS⁠

1. Install packages: brew install mysql redis python3
2. Start services brew services run mysql redis
3. Install mysqlclient pip install mysqlclient

⁠Ssl

Since we're using self singed certificate your OS doesn't know about for development. We need to do some tricks for browser to make it work. If you have valid certificates for your domain you can skip this step.

1. I used the following commands to generate a new self signed certificate. You can use mine located in frontend/certs directory. So you can skip this text

cd frontend/certs
openssl genrsa -out private.key.pem 4096
openssl req -new -sha256 -out root.ca.pem -key private.key.pem -subj '/CN=localhost' -extensions EXT -config <( printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
openssl x509 -req -days 3650 -in root.ca.pem -signkey private.key.pem -out server.crt.pem -extfile ./v3.ext

Useful links:

• https://stackoverflow.com/a/59523186/3872976⁠
• https://stackoverflow.com/a/43665244/3872976⁠
• https://stackoverflow.com/a/56844743/3872976⁠

1. You have multiple options:

• Install development certificate on operating system. Each os will require own configuration. E.g. macos do
  • 
  • Drag and drop for image near localhost to finder
  • Double click on newly created file and go to All items, select localhost and mark it as 'Always trust'
• Click on Proceed unsafe when accessing your site. Proceed unsafe may be unavailable in some cases. E.g. for MacOS chrome you can use hack: just type thisisunsafe⁠ while you see certificate error
• If you use different ports for back and front (like its described above) you may need to accept certificate from localhost:8888 (use for api) as well. For that open https://localhost:8888⁠
• Tell Browser to ignore certificate:
• E.g. for chrome you can enable invalid certificates for localhost in chrome://flags/#allow-insecure-localhost⁠.
• If flag is not available you can also launch chrome with custom flag: --ignore-certificate-errors flag. E.g. on MacOS open -a Google\ Chrome --args --ignore-certificate-errors Remember that Service Worker will work only if certificate is trusted. So flags like ignore-ceritifcate-errors won't work. But installing certifcate to root system will.

⁠Bootstrap files:

1. I use 2 git repos in 2 project directory. So you probably need to rename excludeMAINfile to .gitignoreor create link to exclude. ln -rsf .excludeMAIN .git/info/exclude
2. Rename backend/chat/settings_example.py⁠ to backend/chat/settings.py. Modify file according to the comments in it.
3. From backend dir (cd backend). Create virtualEnv python3 -m venv --system-site-packages .venv. For ubuntu you can omit --system-site-packages . Activate it: source .venv/bin/activate
4. Install python packages with pip install -r requirements.txt. (Remember you're still in backend dir)
5. From root (sudo) user create the database (from shell environment): echo "create database pychat CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci; CREATE USER 'pychat'@'localhost' identified by 'pypass'; GRANT ALL ON pychat.* TO 'pychat'@'localhost';" | mysql -u root. You will need mysql running for that (e.g. systemctl start mysql on archlinux) If you also need remote access do the same with '192.168.1.0/255.255.255.0';
6. Fill database with tables: bash ../download_content.sh create_django_tables. (Remember you're still in backend dir)

⁠Build frontend

Change to frontend directory cd frontend I would recommend to use node version specified in nvm, so nvm install; nvm use.

• To get started install dependencies first: yarn install --frozen-lock # or use npm if you're old and cranky

• Take a look at copy development.json⁠. The description is at Frontend config⁠

• Webpack-dev-server is used for development purposes with hot reloading, every time you save the file it will automatically apply. This doesn't affect node running files, only watching files. So files like builder.js or development.json aren't affected. To run dev-server use yarn run devProxy. Backend should be running during that. Otherwise use yarn run dev. You can navigate to http://localhost:8080⁠.

• To build android use yarn run android -- 192.168.1.55 where 55 is your bridge ip address

• To run electron use yarn run electronDev. This will start electron dev. and generate /tmp/electron.html and /tmp/electron.js

⁠Configure IDEs if you use it:

⁠Pycharm

1. I recommend open backend as root directory for pycharm.
2. Django support should be enabled by default when you open this project. If it doesn't happen go to Settings -> Languages and Framework -> Django -> Enable django support.

• Django project root: backend
• Put Settings: to chat/settings.py

1. If pycharm didn't configure virtualenv itself. Go to Settings -> Project backend -> Project Interpreter -> Cogs in right top -> 'Add' -> Virtual Environment -> Existing environment -> Interpereter = pychatdir/.venv/bin/python. Click ok. In previous menu on top 'Project interpreter` select the interpriter you just added.
2. Settings -> Project backend -> Project structure

• You might want to exclude: .idea
• mark templates directory as Template Folder

1. Add tornado script: Run -> Edit configuration -> Django server -> Checkbox Custom run command start_tornado. Remove port value.

⁠Linting

• atm frontend linting is only available, so cd frotnend
• https://eslint.vuejs.org/rules/this-in-template.html⁠

Current linting supports:

• Sass is linted with stylelint⁠ configured with .stylelintrc⁠
• Typescript are linted with eslint, along with .vue files eslint-plugin-vue⁠ configured with .eslintrc.json⁠

⁠Webstorm

⁠Set template

1. New
2. Edit files templates...
3. Vue single file component

<template>
    <div>#[[$END$]]#</div>
</template>

<script lang="ts">
  import {State} from '@/utils/store';
  import {Component, Prop, Vue, Watch, Ref} from 'vue-property-decorator';

  @Component
  export default class ${COMPONENT_NAME} extends Vue {
   
  }
</script>
<style lang