RNS-Things/MeshChatX
2
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: update README and Android installation guide with new features, installation instructions, and corrected links

Browse Source
This commit is contained in:
ivan
2026-01-03 10:37:54 -06:00
parent 11c4c6729c
commit 5918d0bcbe
2 changed files with 107 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
README.md
View File

@@ -4,27 +4,54 @@ A [Reticulum MeshChat](https://github.com/liamcottle/reticulum-meshchat) fork fr
<video src="https://strg.0rbitzer0.net/raw/62926a2a-0a9a-4f44-a5f6-000dd60deac1.mp4" controls="controls" style="max-width: 100%;"></video>
This project is seperate from the original Reticulum MeshChat project, and is not affiliated with the original project.
This project is separate from the original Reticulum MeshChat project, and is not affiliated with the original project.
> [!WARNING]
> Backup your reticulum-meshchat folder before using, even though MeshChatX will attempt to auto-migrate whatever it can from the old database without breaking things. Its best to keep backups.
> Backup your reticulum-meshchat folder before using! MeshChatX will attempt to auto-migrate whatever it can from the old database without breaking things, but it is best to keep backups.
## Goal
To provide everything you need for Reticulum, LXMF, and LXST in one beautiful and feature-rich application.
- Desktop app
- Self-host on your server easily with or without containers
- Mobile app (one can dream)
## Quick Start (Docker - Recommended)
The easiest way to get MeshChatX running is using Docker. Our official image is multi-arch and supports `linux/amd64` and `linux/arm64` (Raspberry Pi, etc.).
```bash
# Pull and run the latest image
docker pull git.quad4.io/rns-things/meshchatx:latest
# Run MeshChatX in a Docker container
docker run -d \
--name=meshchatx \
-p 8000:8000 \
-v $PWD/storage:/app/storage \
-v $PWD/public:/app/public \
# --network=host \ # Uncomment for autointerface support
git.quad4.io/rns-things/meshchatx:latest
# Or use Docker Compose for an even easier setup
docker compose up -d
```
Check [releases](https://git.quad4.io/RNS-Things/MeshChatX/releases) for pre-built binaries (AppImage, DEB, EXE) if you prefer standalone apps.
## Major Features
- Full LXST support w/ custom voicemail, phonebook, contacts, contact sharing and ringtone support.
- RNS Hot Restart: Reload the entire Reticulum stack from settings without restarting the app.
- Multi-identity support.
- Authentication
- Map (OpenLayers w/ MBTiles upload and exporter for offline maps)
- Security improvements (automatic HTTPS, CORS, and much more)
- Modern Custom UI/UX
- More Tools (RNStatus, RNProbe, RNCP and Translator)
- Built-in page archiving and automatic crawler.
- Block LXMF users, Telephony and NomadNet Nodes
- Toast system for notifications
- i18n support (En, De, Ru)
- Raw SQLite database backend (replaced Peewee ORM)
- LXMF Telemetry support (WIP)
- **Full LXST Support**: Custom voicemail, phonebook, contact sharing, and ringtone support.
- **Multi-Identity**: Switch between multiple Reticulum identities seamlessly.
- **Modern UI/UX**: A completely redesigned, intuitive interface.
- **Integrated Maps**: OpenLayers with MBTiles support for offline maps.
- **Security**: Built-in authentication, automatic HTTPS, and CORS protection.
- **Offline Docs**: Access Reticulum documentation without an internet connection.
- **Powerful Tools**: Includes RNStatus, RNProbe, RNCP, Micron Editor, Paper Message Generator and a Translator.
- **Page Archiving**: Built-in crawler and browser for archived pages.
- **Blocklist**: Block LXMF users, Telephony, and NomadNet Nodes.
- **i18n**: Support for English, German, and Russian.
## Screenshots
@@ -89,23 +116,25 @@ This project is seperate from the original Reticulum MeshChat project, and is no
</details>
## TODO
### Pipx / Global Installation
- [ ] RNS hot reload fix
- [ ] Offline Reticulum documentation tool
- [ ] Spam filter (based on keywords)
- [ ] TAK tool/integration
- [ ] RNS Tunnel - tunnel your regular services over RNS to another MeshchatX user.
- [ ] RNS Filesync - P2P file sync
- [ ] RNS Page Node
If you prefer to install MeshChatX globally using `pipx, pip or uv`, you can do so directly from the repository. However, you must specify the path to your built frontend files using the `--public-dir` flag or `MESHCHAT_PUBLIC_DIR` environment variable, as the static files are not bundled with the source code. The release .whl packages include the built frontend files and also there is a seperate frontend zip to grab and use.
## Usage
1. **Install MeshChatX**:
Check [releases](https://git.quad4.io/Ivan/MeshChatX/releases) for pre-built binaries or appimages.
```bash
pipx install git+https://git.quad4.io/RNS-Things/MeshChatX
```
### Manual Installation (Bare Metal)
2. **Run with Frontend Path**:
```bash
# Replace /path/to/MeshChatX/meshchatx/public with your actual path
meshchat --public-dir /path/to/MeshChatX/meshchatx/public
```
If you prefer not to use Docker or pre-built binaries, you can install MeshChatX manually:
### Manual Installation (From Source)
If you want to run MeshChatX from the source code locally:
1. **Clone the repository**:
@@ -114,187 +143,85 @@ If you prefer not to use Docker or pre-built binaries, you can install MeshChatX
cd MeshChatX
```
2. **Install Node.js dependencies**:
2. **Build the Frontend**:
Requires Node.js and pnpm.
```bash
corepack enable
pnpm install
```
3. **Install Python dependencies**:
```bash
# It is recommended to use a virtual environment
pip install poetry
poetry install
```
4. **Build the frontend**:
```bash
pnpm run build-frontend
```
5. **Run MeshChatX**:
3. **Install & Run Backend**:
Requires Python 3.10+ and Poetry.
```bash
pip install poetry
poetry install
poetry run meshchat --headless --host 127.0.0.1
```
## Architecture Support (ARM64, etc.)
MeshChatX fully supports **ARM64** (Raspberry Pi, Pine64, etc.) and other architectures via Docker or manual installation.
### Docker (Recommended for ARM64)
The official Docker image is multi-arch and supports `linux/amd64` and `linux/arm64`.
```bash
# On a Raspberry Pi, simply pull and run
docker pull git.quad4.io/rns-things/meshchatx:latest
```
### Manual Build for ARM64
If you are building your own multi-arch image:
```bash
DOCKER_PLATFORMS=linux/amd64,linux/arm64 task build-docker
```
## Configuration
MeshChatX can be configured via command-line arguments or environment variables. Environment variables are particularly useful when running in Docker.
MeshChatX can be configured via command-line arguments or environment variables.
| Argument | Environment Variable | Default | Description |
| :----------------------- | :------------------------------ | :------------- | :------------------------------------------- |
| `--host` | `MESHCHAT_HOST` | `127.0.0.1` | The address the web server should listen on. |
| `--port` | `MESHCHAT_PORT` | `8000` | The port the web server should listen on. |
| `--no-https` | `MESHCHAT_NO_HTTPS` | `false` | Disable HTTPS and use HTTP instead. |
| `--headless` | `MESHCHAT_HEADLESS` | `false` | Don't launch the web browser automatically. |
| `--auth` | `MESHCHAT_AUTH` | `false` | Enable basic authentication. |
| `--auto-recover` | `MESHCHAT_AUTO_RECOVER` | `false` | Attempt auto-recovery of SQLite database. |
| `--storage-dir` | `MESHCHAT_STORAGE_DIR` | `./storage` | Path for databases and config files. |
| `--reticulum-config-dir` | `MESHCHAT_RETICULUM_CONFIG_DIR` | `~/.reticulum` | Path to Reticulum config directory. |
| `--identity-file` | `MESHCHAT_IDENTITY_FILE` | - | Path to a Reticulum Identity file. |
| `--identity-base64` | `MESHCHAT_IDENTITY_BASE64` | - | Base64 encoded Reticulum Identity. |
| `--identity-base32` | `MESHCHAT_IDENTITY_BASE32` | - | Base32 encoded Reticulum Identity. |
| Argument | Environment Variable | Default | Description |
| :-------------- | :--------------------- | :---------- | :------------------- |
| `--host` | `MESHCHAT_HOST` | `127.0.0.1` | Web server address |
| `--port` | `MESHCHAT_PORT` | `8000` | Web server port |
| `--no-https` | `MESHCHAT_NO_HTTPS` | `false` | Disable HTTPS |
| `--headless` | `MESHCHAT_HEADLESS` | `false` | Don't launch browser |
| `--auth` | `MESHCHAT_AUTH` | `false` | Enable basic auth |
| `--storage-dir` | `MESHCHAT_STORAGE_DIR` | `./storage` | Data directory |
| `--public-dir` | `MESHCHAT_PUBLIC_DIR` | - | Frontend files path |
## Building
## GPG Verification
This project uses [Task](https://taskfile.dev/) for build automation. Install Task first, then:
To ensure the security and authenticity of this project, all commits and releases are GPG signed. You can verify the signatures of the commits using the following steps:
### 1. Import the Developer's Public Key
Fetch the public key from the Gitea instance and import it into your GPG keyring:
```bash
task install # installs Python deps via Poetry and Node deps via pnpm
task build
# Replace YOUR_TOKEN if the instance requires authentication
curl -s "https://git.quad4.io/api/v1/users/Ivan/gpg_keys" | jq -r '.[0].public_key' | gpg --import
```
### Development with Nix
### 2. Verify Commits
If you use [Nix](https://nixos.org/), a `flake.nix` is provided for a complete development environment including Python, Node.js, and all packaging tools.
Once the key is imported, you can verify the commits in your local clone:
```bash
nix develop
# Show signatures for the last 10 commits
git log --show-signature -n 10
```
You can run `task run` or `task develop` (a thin alias) to start the backend + frontend loop locally through `poetry run meshchat`.
You should see "Good signature from Ivan <ivan@quad4.io>" with the Key ID `1E0B37EE76428197`.
### Available Tasks
## Development
| Task | Description |
| ---------------------------- | ------------------------------------------------------------------------------- |
| `task install` | Install all dependencies (syncs version, installs node modules and python deps) |
| `task node_modules` | Install Node.js dependencies only |
| `task python` | Install Python dependencies using Poetry only |
| `task sync-version` | Sync version numbers across project files |
| `task run` | Run the application |
| `task develop` | Run the application in development mode (alias for `run`) |
| `task build` | Build the application (frontend and backend) |
| `task build-frontend` | Build only the frontend |
| `task clean` | Clean build artifacts and dependencies |
| `task wheel` | Build Python wheel package (outputs to `python-dist/`) |
| `task build-appimage` | Build Linux AppImage |
| `task build-exe` | Build Windows portable executable |
| `task dist` | Build distribution (defaults to AppImage) |
| `task electron-legacy` | Install legacy Electron version |
| `task build-appimage-legacy` | Build Linux AppImage with legacy Electron version |
| `task build-exe-legacy` | Build Windows portable executable with legacy Electron version |
| `task build-docker` | Build Docker image using buildx |
| `task run-docker` | Run Docker container using docker-compose |
We use [Task](https://taskfile.dev/) for automation.
All tasks support environment variable overrides. For example:
| Task | Description |
| :-------------- | :---------------------------------- |
| `task install` | Install all dependencies |
| `task run` | Run the application |
| `task lint` | Run all linters (Python & Frontend) |
| `task format` | Format all code (Python & Frontend) |
| `task test` | Run all tests |
| `task test:cov` | Run tests with coverage reports |
| `task build` | Build frontend and backend |
- `PYTHON=python3.12 task install`
- `DOCKER_PLATFORMS=linux/amd64,linux/arm64 task build-docker`
## TODO
### Python Packaging
The backend uses Poetry with `pyproject.toml` for dependency management and packaging. `package.json` is the source of truth for the project version. When you run `task install` (or any task that builds/runs the app), the version is automatically synced to `pyproject.toml` and `src/version.py`. This keeps the CLI release metadata, wheel packages, and other bundles aligned with the Electron build.
#### Build Artifact Locations
Both `poetry build` and `python -m build` generate wheels inside the default `dist/` directory. The `task wheel` shortcut wraps `poetry build -f wheel` and then runs `python scripts/move_wheels.py` to relocate the generated `.whl` files into `python-dist/` (the layout expected by `scripts/test_wheel.sh` and the release automation). Use `task wheel` if you need the artifacts in `python-dist/`; `poetry build` or `python -m build` alone will leave them in `dist/`.
#### Building with Poetry
```bash
# Install dependencies
poetry install
# Build the package (wheels land in dist/)
poetry build
# Install locally for testing (consumes dist/)
pip install dist/*.whl
```
#### Building with pip (alternative)
If you prefer pip, you can build/install directly:
```bash
# Build the wheel
pip install build
python -m build
# Install locally
pip install .
```
### Building in Docker
```bash
task build-docker
```
`build-docker` creates `reticulum-meshchatx:local` (or `$DOCKER_IMAGE` if you override it) via `docker buildx`. Set `DOCKER_PLATFORMS` to `linux/amd64,linux/arm64` when you need multi-arch images, and adjust `DOCKER_BUILD_FLAGS`/`DOCKER_BUILD_ARGS` to control `--load`/`--push`.
### Running with Docker Compose
```bash
task run-docker
```
`run-docker` feeds the locally-built image into `docker compose -f docker-compose.yml up --remove-orphans --pull never reticulum-meshchatx`. The compose file uses the `MESHCHAT_IMAGE` env var so you can override the target image without editing the YAML (the default still points at `ghcr.io/sudo-ivan/reticulum-meshchatx:latest`). Use `docker compose down` or `Ctrl+C` to stop the container.
The Electron build artifacts will still live under `dist/` for releases.
### Standalone Executables (cx_Freeze)
The `cx_setup.py` script uses cx_Freeze for creating standalone executables (AppImage for Linux, NSIS for Windows). This is separate from the Poetry/pip packaging workflow.
## Internationalization (i18n)
Multi-language support is in progress. We use `vue-i18n` for the frontend.
Translation files are located in `meshchatx/src/frontend/locales/`.
Currently supported languages:
- English (Primary)
- Russian
- German
- [ ] RNS hot reload fix
- [ ] Offline Reticulum documentation tool
- [ ] Spam filter (based on keywords)
- [ ] TAK tool/integration
- [ ] RNS Tunnel - tunnel regular services over RNS
- [ ] RNS Filesync - P2P file sync
## Credits
- [Liam Cottle](https://github.com/liamcottle) - Original Reticulum MeshChat
- [micron-parser-js](https://github.com/RFnexus/micron-parser-js) by [RFnexus](https://github.com/RFnexus)
- [RFnexus](https://github.com/RFnexus) - [micron-parser-js](https://github.com/RFnexus/micron-parser-js)

4
docs/meshchat_on_android_with_termux.md
View File

@@ -20,7 +20,7 @@ pkg install build-essential
### Download and Install Wheel
Download the latest wheel from the [releases page](https://git.quad4.io/Ivan/MeshChatX/releases), then:
Download the latest wheel from the [releases page](https://git.quad4.io/RNS-Things/MeshChatX/releases), then:
```
pip install reticulum_meshchatx-*-py3-none-any.whl
@@ -62,7 +62,7 @@ corepack prepare pnpm@latest --activate
### Clone and Build
```
git clone https://git.quad4.io/Ivan/MeshChatX.git
git clone https://git.quad4.io/RNS-Things/MeshChatX.git
cd MeshChatX
pip install poetry
poetry install