https://github.com/richtersfinger/peerchat
A basic self-hosted peer-to-peer chat application.
https://github.com/richtersfinger/peerchat
chat-application flask peer-to-peer python3 react self-hosted socket-io typescript
Last synced: 4 months ago
JSON representation
A basic self-hosted peer-to-peer chat application.
- Host: GitHub
- URL: https://github.com/richtersfinger/peerchat
- Owner: RichtersFinger
- License: mit
- Created: 2024-11-26T20:44:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-30T11:39:19.000Z (about 1 year ago)
- Last Synced: 2025-03-30T11:46:49.916Z (about 1 year ago)
- Topics: chat-application, flask, peer-to-peer, python3, react, self-hosted, socket-io, typescript
- Language: TypeScript
- Homepage: https://pypi.org/project/peerChat/
- Size: 1.13 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# peerChat
A basic self-hosted peer-to-peer chat application written in python (Flask+Socket.IO-backend) and TypeScript (React-frontend).
It is
* platform-independent,
* easy to setup and use,
and offers for example
* message queues (auto-resend if peers are offline),
* support for markdown,
* desktop notifications, and
* installing application updates via UI.
See the [demo-gallery](./gallery/gallery.md) for some impressions.
## Install
`peerChat` can be installed using `pip` by entering
```
pip install peerChat
```
It is recommended to use a virtual environment
```
python3 -m venv venv
source venv/bin/activate
```
## Run
Start the `peerChat`-application with
```
peerChat
```
By default, the web-UI is available at `http://localhost:27182`.
If you are done, stop by hitting `Ctrl`+`C`.
When the UI is first opened, some configuration has to be performed.
Follow the dialog shown in the UI to set a key (or password) that will be used to authenticate with the server.
Note that this key will be stored unencrypted in your file system (`peerChat` is intended to be run locally so usually that key will never leave the local machine).
After this technical setup is complete, your profile can be customized by selecting `Settings` in the context menu at the top of the sidebar.
Here, most importantly, you should set your public network address to ensure your peers can respond to your messages.
## Update
Run
```
pip install peerChat --upgrade
```
to get the latest version.
## Running as a systemd-service
The `peerChat`-app can be run as a systemd-service (linux) that automatically starts with the system.
After cloning this repository, simply run
```
make service
```
for a default configuration (install/working directory is given by `~/.local/share/peerChat` and the service-file is written to `~/.config/systemd/user/peerChat.service`).
Check the service's status with
```
systemctl --user status peerChat.service
```
Disable or stop the service by entering
```
systemctl --user peerChat.service
```
## Docker
Run with, for example,
```
docker run -p 27182:27182 ghcr.io/richtersfinger/peerchat:latest
```
The container's `peerChat`-working directory is located at `/app`.
## Building from source
The provided `Makefile` provides targets for building from source.
Run
* `make build` to build the python package bundled with the static client (react)
* the distribution-files can be found in `backend/dist`
* the build version can be set with `make build VERSION="1.0.0.post5+a6cd1d01"`
* the client build can be skipped with `make build SKIP_CLIENT="yes"`
* `make clean` to remove build artifacts
A build requires `npm` as well as the `venv`-module of `python3` to be successful.
## Authorization-concept
Since the service is intended for self-hosting, it only supports a single user per running instance of `peerChat`.
In order to identify a user, a (automatically generated or user-defined) key is used.
The backend-API allows to configure this key only once.
To reset that key, the corresponding key-file `.peerChat.auth` can be deleted.
After deleting, the service needs to be restarted for changes to take effect.
## Environment configuration
The following environment variables can be set to configure peerChat:
- `PORT` [DEFAULT 27182] peerChat port
- `WORKING_DIRECTORY` [DEFAULT ".peerChat"] working directory of the application; default is the subdirectory `.peerChat` in the current working directory
- `SECRET_KEY` [DEFAULT null] override the otherwise automatically generated secret key
- `USER_PEER_URL` [DEFAULT null] can be used to set the public peer-url; can also be set via the UI
- `MODE` [DEFAULT prod] execution mode; one of "prod" or "dev"
- `USE_NOTIFICATIONS` [DEFAULT yes] whether to enable desktop notifications (using the [`desktop-notifier`](https://pypi.org/project/desktop-notifier/)-package)
- `CLIENT_URL` [DEFAULT null] override default client-url (used for example in notifications)
Extended options for configuration can be accessed via the `AppConfig`-class used by the underlying `flask`-webserver which is passed in to the app-factory.
### Public API
The public part of the `peerChat`-API can be used to
* fetch information on a given peer,
* post messages, and
* notify of changes.
Please refer to the OpenAPI v3-document `openapi.yaml` for details.
### Running in dev-mode
The development setup requires both `python3` and the node package manager `npm` to be installed.
Contrary to the pure python production server, back- and frontend are run separately in the development context.
To run the backend server, enter
```
cd backend
python3 -m venv venv
source venv/bin/activate
pip install .
pip install -r dev-requirements.txt
MODE=dev flask run
```
Based on pre-defined scripts, the frontend development server can be started with
```
cd frontend
npm install
npm start
```
The client can then be accessed via the node-development server at `http://localhost:3000`.