diff --git a/README.md b/README.md index 8457f2a1e3..7efa69e742 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,47 @@ # Matron Server -[Matron](https://matron.chat) is a chat system for talking to Claude Code -agents from your phone, desktop, or browser. This repository is the Matrix -homeserver used by Matron's Matrix transport: clients connect to it over the -Matrix protocol, and [claude-matrix-bridge](https://github.com/Matronhq/claude-matrix-bridge) -relays messages between Matrix rooms and Claude Code sessions. +> **Status: legacy.** Matron's current stack uses +> [matron-journal](https://github.com/Matronhq/matron-journal) as its sync +> server; the Matrix transport this homeserver served has been retired +> ([matron-bridge](https://github.com/Matronhq/matron-bridge) is journal-only, +> and [dev-boxer](https://github.com/Matronhq/dev-boxer) no longer installs a +> homeserver — see its "Upgrading from a Matrix-era install" section for +> migration). This repo is kept as a mirror of upstream Tuwunel for existing +> Matrix-era deployments. -Matron Server is Matron's Matrix homeserver distribution, tracking -[Tuwunel](https://github.com/matrix-construct/tuwunel) upstream. + -This fork intentionally keeps Tuwunel's native binary, crate, and configuration -prefixes for now. Use `TUWUNEL_` environment variables and Tuwunel's upstream -configuration docs unless a Matron-specific deployment wrapper says otherwise. +Matron Server is a fork of +[Tuwunel](https://github.com/matrix-construct/tuwunel), a Matrix homeserver +written in Rust. + + + + + +It was the homeserver behind [Matron](https://matron.chat)'s Matrix transport: +clients connected to it over the Matrix protocol, and +[matron-bridge](https://github.com/Matronhq/matron-bridge) relayed messages +between Matrix rooms and Claude Code sessions. That transport has been +retired; this repository stays close to upstream so existing Matrix-era +deployments can keep pulling a current server image. + +## Versions + +This tree tracks Tuwunel **1.6.0**; upstream is at 1.8.x (latest release +v1.8.3). The `ghcr.io/matronhq/matron-server:latest` image is a weekly re-tag +of `ghcr.io/matrix-construct/tuwunel:latest` (see +[`.github/workflows/sync-image.yml`](.github/workflows/sync-image.yml)) and +does **not** correspond to the source in this repo. + +## Naming + +The fork keeps Tuwunel's native names throughout: the crate and binary are +`tuwunel`, the default database path uses `/var/lib/tuwunel`, and +configuration uses `TUWUNEL_` environment variables (`CONDUWUIT_` and +`CONDUIT_` prefixes are also accepted for compatibility with upstream +history). Follow Tuwunel's upstream configuration docs unless a +Matron-specific deployment wrapper says otherwise. ## Part of the Matron ecosystem @@ -19,28 +49,22 @@ configuration docs unless a Matron-specific deployment wrapper says otherwise. |---------|-------------| | [Matron Desktop](https://github.com/Matronhq/matron-desktop) | Desktop client | | [Matron Web](https://github.com/Matronhq/matron-web) | Web client | -| [Matron iOS](https://github.com/Matronhq/matron-apple) | iOS client | -| **Matron Server** | Matrix homeserver (this repo) | -| [Matron Journal](https://github.com/Matronhq/matron-journal) | Sync server for Matron's native journal transport | -| [claude-matrix-bridge](https://github.com/Matronhq/claude-matrix-bridge) | Runs Claude Code sessions and bridges them to Matrix and the journal | +| [Matron Apple](https://github.com/Matronhq/matron-apple) | iPhone and Mac client | +| [Matron Android](https://github.com/Matronhq/matron-android) | Android client | +| **Matron Server** | Matrix homeserver (this repo — legacy) | +| [Matron Journal](https://github.com/Matronhq/matron-journal) | Sync server — the current Matron backbone | +| [matron-bridge](https://github.com/Matronhq/matron-bridge) | Ran Claude Code sessions and bridged them to Matrix (now journal-only) | | [Dev Boxer](https://github.com/Matronhq/dev-boxer) | One-command dev environment setup | -## Upstream - -This repository is kept close to upstream Tuwunel. The codebase, binary name, -database path, and environment variable prefix still use upstream `tuwunel` and -`TUWUNEL_` names so the fork can be updated with minimal conflicts. +## Container image -Matron-specific changes should stay small and documented. If Matron later needs -its own binary names or config prefixes, add that as a compatibility layer rather -than a repo-wide source rename. +The `ghcr.io/matronhq/matron-server:latest` image is mirrored weekly from +`ghcr.io/matrix-construct/tuwunel:latest` — it is upstream's current build, +not a build of this tree (see [Versions](#versions)). -## Container Image - -The `ghcr.io/matronhq/matron-server:latest` image is mirrored from -`ghcr.io/matrix-construct/tuwunel:latest`. - -Use Tuwunel's native environment variables when configuring the container: +Use Tuwunel's native environment variables when configuring the container. +The server listens on port 8008 by default; this example moves it to 6167 to +match [`docs/deploying/docker-compose.yml`](docs/deploying/docker-compose.yml): ```bash docker run -d \ @@ -48,6 +72,7 @@ docker run -d \ -p 6167:6167 \ -v matron_server_data:/var/lib/tuwunel \ -e TUWUNEL_SERVER_NAME="matrix.example.com" \ + -e TUWUNEL_PORT="6167" \ -e TUWUNEL_DATABASE_PATH="/var/lib/tuwunel" \ -e TUWUNEL_ALLOW_REGISTRATION="false" \ ghcr.io/matronhq/matron-server:latest @@ -55,7 +80,7 @@ docker run -d \ ## Build from source -The crate and binary are still named `tuwunel` (see [Upstream](#upstream)): +The crate and binary are named `tuwunel` (see [Naming](#naming)): ```bash cargo build --release @@ -78,21 +103,30 @@ database_path = "/var/lib/tuwunel" ``` Configuration can also be supplied through environment variables with the -`TUWUNEL_` prefix. For compatibility with upstream history, `CONDUWUIT_` and -`CONDUIT_` prefixes are still accepted by the server. +`TUWUNEL_` prefix. ## Development -This repository tracks Tuwunel upstream first. Keep Matron-specific changes -focused on public metadata, documentation, packaging, and release automation. +CI in this repository runs metadata and hygiene checks only +(`cargo metadata`, whitespace, workflow YAML validation, string scans) — +it does not build or test the server source. For project layout and build documentation, +see [development.md](development.md) and the mdBook under +[`docs/`](docs/). Substantive changes to server behavior belong upstream — +see [CONTRIBUTING.md](CONTRIBUTING.md). -Useful local checks: +## Links -```bash -git diff --check -cargo metadata --no-deps --locked --format-version 1 -``` +- [CONTRIBUTING.md](CONTRIBUTING.md) — how and where to contribute +- [RELEASE.md](RELEASE.md) — Tuwunel 1.6.0 release notes (the version this tree tracks) +- [`docs/`](docs/) — mdBook documentation source +- [Tuwunel](https://github.com/matrix-construct/tuwunel) — upstream project + + + + ## License Apache-2.0. See [LICENSE](LICENSE). + +