Metadata-Version: 2.4
Name: peerChat
Version: 0.7.2
Summary: A basic self-hosted peer-to-peer chat application.
Home-page: https://pypi.org/project/peerChat/
Author: Steffen Richters-Finger
Author-email: srichters@uni-muenster.de
License: MIT
Project-URL: Source, https://github.com/RichtersFinger/peerChat
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Communications
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Flask
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Flask<4,>=3
Requires-Dist: Flask-SocketIO<6,>=5.4
Requires-Dist: requests<3,>=2.32
Requires-Dist: gunicorn
Requires-Dist: desktop-notifier<7,>=6
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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 <disable|stop> peerChat.service
```

## 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`.
