From 83b6042d544b5f8b0e2b0b457d7234fc194556cd Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Wed, 28 May 2025 00:27:46 +0000 Subject: [PATCH] Update README (fixes #28). Signed-off-by: Jason Volk --- README.md | 113 ++++++++++++++++++++++++++++++++------ docs/deploying/README.md | 1 + docs/deploying/SUMMARY.md | 9 +++ 3 files changed, 106 insertions(+), 17 deletions(-) create mode 120000 docs/deploying/README.md create mode 100644 docs/deploying/SUMMARY.md diff --git a/README.md b/README.md index 1c49224a..0fdbc457 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,122 @@ # Tuwunel 🎔 -![GitHub Repo stars](https://img.shields.io/github/stars/matrix-construct/tuwunel?style=flat&color=%23fcba03&link=https%3A%2F%2Fgithub.com%2Fmatrix-construct%2Ftuwunel) ![GitHub commit activity](https://img.shields.io/github/commit-activity/m/matrix-construct/tuwunel?style=flat&color=%2303fcb1&link=https%3A%2F%2Fgithub.com%2Fmatrix-construct%2Ftuwunel%2Fpulse%2Fmonthly) ![GitHub Created At](https://img.shields.io/github/created-at/matrix-construct/tuwunel) ![GitHub License](https://img.shields.io/github/license/matrix-construct/tuwunel) +[![CI/CD](https://github.com/matrix-construct/tuwunel/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/matrix-construct/tuwunel/actions/workflows/main.yml) +![GitHub Repo stars](https://img.shields.io/github/stars/matrix-construct/tuwunel?style=flat&color=%23fcba03&link=https%3A%2F%2Fgithub.com%2Fmatrix-construct%2Ftuwunel) +![GitHub commit activity](https://img.shields.io/github/commit-activity/m/matrix-construct/tuwunel?style=flat&color=%2303fcb1&link=https%3A%2F%2Fgithub.com%2Fmatrix-construct%2Ftuwunel%2Fpulse%2Fmonthly) +![GitHub Created At](https://img.shields.io/github/created-at/matrix-construct/tuwunel) +![GitHub License](https://img.shields.io/github/license/matrix-construct/tuwunel) -## High Performance [Matrix](https://matrix.org/) Chat Homeserver in Rust! +## High Performance Matrix Homeserver in Rust! -### Status +Tuwunel is a featureful [Matrix](https://matrix.org/) federation homeserver you can use instead of Synapse +with your favorite Matrix [client](https://matrix.org/ecosystem/clients/), +[bridge](https://matrix.org/ecosystem/bridges/) or +[bot](https://matrix.org/ecosystem/integrations/). The server is written entirely in Rust as a scalable, +low-cost, lightweight, community-driven alternative covering all but the most niche use-cases. -Tuwunel is a successor to conduwuit. We are currently in the process of transitioning. -The software is just as great as before. Please bear with us. +This project is the official successor to [conduwuit](https://github.com/girlbossceo/conduwuit), which +was a featureful and high-performance fork of [Conduit](https://gitlab.com/famedly/conduit), all +community-lead alternatives to Synapse implementing the compatible +[Matrix Specification](https://spec.matrix.org/latest/). -### Goals +Tuwunel is operated by enterprise users with a vested interest in sponsoring its continued +development. It is now maintained by full-time staff. -**Maximum Performance.** Tuwunel relentlessly pursues optimization, embracing hardware -acceleration with the highest throughput and lowest latency for messages. +### Getting Started -**Unlimited Features.** Tuwunel is working toward a fully modular design to leverage -the widest number of contributor features. Our goal is to never have to say no to your ideas. +1. Download Tuwunel + - [GitHub Releases](https://github.com/matrix-construct/tuwunel/releases) + - [Sourcecode](https://github.com/matrix-construct/tuwunel/) `git clone https://github.com/matrix-construct/tuwunel.git` + - [DockerHub](https://hub.docker.com/r/jevolk/tuwunel) or `docker pull jevolk/tuwunel:latest` + - [GHCR](https://github.com/matrix-construct/tuwunel/pkgs/container/tuwunel) or `docker pull ghcr.io/matrix-construct/tuwunel:latest` + - Deb and RPM packages are available and this will be updated with a link. + - Arch Package is expected very soon and this will be updated. + - Nix Package has not yet been updated but expect this soon. -#### Can I migrate or switch from Conduwuit? +2. [Configure](https://github.com/matrix-construct/tuwunel/blob/main/docs/configuration.md) by copying and editing the `tuwunel-example.toml`. **Most users deploy via docker or a distribution package and should follow the [appropriate guide](https://github.com/matrix-construct/tuwunel/tree/main/docs/deploying) instead**. This is just a summary for the impatient. See the full [documentation](https://github.com/matrix-construct/tuwunel/blob/main/docs/). -Yes. + - Setting the `server_name` and `database_path` is required. + - The `registration_token` is the easiest method to enable `allow_registration = true`. -#### Can I migrate or switch from Conduit? + 👉 Avoid using a sub-domain for your `server_name`. You can always delegate `example.com` to `matrix.example.com` by setting up a [`.well-known`](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-well-known.md) file later, but you can never change your `server_name`. -No. +3. Setup TLS certificates. Most users enjoy the [Caddy](https://caddyserver.com/) reverse-proxy which automates their certificate renewal. Advanced users can load their own TLS certificates using the configuration and Tuwunel can be deployed without a reverse proxy. Example `/etc/caddy/Caddyfile` configuration with [Element-web](https://github.com/element-hq/element-web/releases) unzipped in `/var/www/element`: + ``` + https://tuwunel.me:8448 { + reverse_proxy http://127.0.0.1:8008 + } -#### Can I migrate from Synapse? + https://tuwunel.me:443 { + root * /var/www/element/ + file_server + } + ``` + `caddy reload --config /etc/caddy/Caddyfile` + + + 🤗 Did you find this and other documentation helpful? We would love your feedback when setting up Tuwunel. _No problem is your fault_. Please open an issue to help us streamline. + + +### Migrating to Tuwunel + +| Can I migrate from | | +|-----------------|-----------| +| conduwuit? | ✅ Yes. This will be supported at a minimum for one year, but likely indefinitely. | +| Synapse? | ❌ Not yet, but this is planned and an important issue. Subscribe to [#2](https://github.com/matrix-construct/tuwunel/issues/2). | +| Conduit? | ❌ Not right now, but this is planned and expected in the near future. Subscribe to [#41](https://github.com/matrix-construct/tuwunel/issues/41). | +| Another domain? | ❌ No. Matrix does not yet support changing your domain. The `server_name` you choose is permanent. | +| Any other fork of Conduit? | ❌ **Never switch between different derivatives of Conduit or you will corrupt your database.** Even if it appears to be working fine for a while, the corruption is often silent and the damage is permanent. We cannot help you the moment you run another fork without a migration path explicitly sanctioned by Tuwunel in this table. | + + +#### Migrating from conduwuit + +Migrating from conduwuit to Tuwunel _just works_. In technical parlance it is a "binary swap." +All you have to do is update to the latest Tuwunel and change the path to the executable from +`conduwuit` to `tuwunel`. + +Anything else named "conduwuit" is still recognized, this includes environment variables with prefixes +such as `CONDUWUIT_`. In fact, `CONDUIT_` is still recognized for our legacy users. You may have +noticed that various configs, yamls, services, users, and other items were renamed, but if you +were a conduwuit user we recommend against changing anything at all. This will keep things simple. +If you are not sure please ask. If you found out that something did in fact need to be changed +please open an issue immediately. + + +### Getting Help & Support + +The official community will be found at [#tuwunel:tuwunel.chat](https://matrix.to/#/#tuwunel:tuwunel.chat). +If this is currently inaccessible please be patient as it's still coming online at the time of +the first release; we will have updates to this section. This is a fully moderated space to protect +the wellbeing of our users and create a non-toxic work environment for staff. Users will not have +permission to post by default. Additional access is granted on an as-needed/as-trusted basis. +If you require assistance with anything that is not remedied by the documentation, please open +an issue on github. If discussion is required we will grant access at that point. + +If you are opposed to using github, or private discussion is required, or for any other reason, +I would be happy to receive your DM at [@jason:tuwunel.me](https://matrix.to/#/@jason:tuwunel.me), +you will not be bothering me and it would be my pleasure to help you anytime. As an emergency contact +you can send an email to jasonzemos@gmail.com. + +##### Tuwunel Fanclub + +We also have an unofficial community-run chat which is publicly accessible at +[#tuwunel:grin.hu](https://matrix.to/#/#tuwunel:grin.hu). The members, content, or moderation +decisions of this room are not in any way related or endorsed by this project or its sponsors, +and not all project staff will be present there. There will be at least some presence by staff to +offer assistance so long as the room remains in minimally good standing. -No, but this is planned. ## Tuwunel 🎔 -Tuwunel's theme is **empathy in communication** defined by the works of [Edith Stein](https://plato.stanford.edu/entries/stein/). +Tuwunel's theme is **empathy** in communication defined by the works of +[Edith Stein](https://plato.stanford.edu/entries/stein/). Empathy is the basis for how we approach +every message, and a reminder for how we should all conduct ourselves in every conversation. diff --git a/docs/deploying/README.md b/docs/deploying/README.md new file mode 120000 index 00000000..0fbb5a86 --- /dev/null +++ b/docs/deploying/README.md @@ -0,0 +1 @@ +SUMMARY.md \ No newline at end of file diff --git a/docs/deploying/SUMMARY.md b/docs/deploying/SUMMARY.md new file mode 100644 index 00000000..dcdcdc63 --- /dev/null +++ b/docs/deploying/SUMMARY.md @@ -0,0 +1,9 @@ +# Deployment Guides + +- [Generic](generic.md) +- [NixOS](nixos.md) +- [Docker](docker.md) +- [Kubernetes](kubernetes.md) +- [Arch Linux](arch-linux.md) +- [Debian](debian.md) +- [FreeBSD](freebsd.md)