Telodendria

Telodendria: The terminal branches of an axon.

Note: Telodendria is under heavy development. Please see the Project Status.

Telodendria is a Matrix homeserver implementation written from scratch in ANSI C. It is designed to be lightweight and simple, yet functional. Telodendria differentiates itself from other Matrix homeserver implementations because it:

Telodendria is on Matrix! Check out the official Matrix rooms:

Room Description
#telodendria-releases:bancino.net Get notified of new releases.
#telodendria-general:bancino.net General discussion and support for Telodendria.
#telodendria-issues:bancino.net Report issues with Telodendria.
#telodendria-patches:bancino.net Submit code patches to the Telodendria project.

Table of Contents

Download

Telodendria is distributed as source tarballs, in true Unix fashion. If you want, you can verify the checksum of your download, and check the signature. To check the signature, you'll need signify, and the signify public key: telodendria-signify.pub.

If your operating system has an official package or port of Telodendria, you should prefer to use that instead of manually downloading the source and building it. If your operating system's package or port is too out of date for your tastes, please contact the package's maintainers to notify them, or offer to update the package yourself.

Version Download Checksum Signature
v0.0.0 Telodendria-v0.0.0.tar.gz SHA256 Signify

You can check out the change log here.

Building The Source

Telodendria is designed to be light enough that it can be built from source on just about any operating system. It only has the following requirements, all of which should be already available to you on a sufficiently complete operating system:

$ ./make.sh

If everything went well, that will produce telodendria.cgi, which you can then place under your web root and configure your web server to execute. You'll need to make sure /.well-known/matrix and /_matrix and all the paths under them actually execute telodendria.cgi. See the provided OpenBSD httpd.conf for reference. Even if you aren't using OpenBSD's httpd(8), you should find its configuration syntax simple enough to adequately demonstrate the proper configuration.

Configure Telodendria

Once you get Telodendria built and hooked into your web server, you will have to write a configuration file for it. The configuration file is just JSON, and it should be called Telodendria.json.

Project Status

Telodendria is a very ambitious project. There's a lot that needs to happen yet before it is usable. At the moment, there's nothing that even remotely resembles a Matrix homeserver here; I'm still getting off the ground and building a foundation.

But just because there's nothing here yet doesn't mean you should go away! I could always use help, so you are more than welcome to help out if you want things to go quicker. Please see the Contributing section for details on how you can get involved.

Phase 1: Getting Off The Ground

Phase 2: Building A Foundation

Phase 3: Welcome To Matrix

Phase 4: A Real Homeserver

Documentation Status

This documentation needs just a little work. Here's the things on my list for that:

Rationale

This section explains

I want a lightweight Matrix homeserver designed for OpenBSD. I want a homeserver that can be developed in vi(1) and compiled with a C compiler. I want it to function entirely on a base OpenBSD install without having to install any extra packages whatsoever. I've found that the existing homeserver implementations are way over-engineered and written in such a way that many programs and libraries have to be pulled in to use them. I also want to learn how Matrix works, and I want to understand the code I'm running on my server.

So I wrote Telodendria.

Telodendria is written entirely in portable ANSI C. It depends on no third-party C libraries other than the standard C library. The only thing you need to run it is a web server that supports executing CGI programs, and a directory that data can be written to. Everything Telodendria needs to run itself is compiled into a single static binary, and the source code can be built anywhere, right out of the box.

Telodendria doesn't use a database like all the other homeservers. Instead, it operates more like email: it uses a flat-file data structure similar to maildir to store data. The advantage of this is that it saves server maintainers from also having to maintain a database. It greatly simplifies the process of getting a Matrix homeserver up and running, and it makes it highly portable. It also is extremely easy to back up and restore with base tools; just tar(1) up the directory, and you're good to go.

Telodendria is developed and tested on OpenBSD, but you'll find that it should run under any web server that supports CGI. I chose to write Telodendria as a CGI program because anyone running an existing Matrix server is likely running a web server acting as a reverse proxy in front of it anyway, so why not just hook the homeserver directly into the web server? That's one less daemon to run, which means memory and CPU savings. CGI also allows Telodendria to remain single-threaded. Each request that comes in is handled as its own process, and operations are entirely isolated.

Project Goals

The goals of this project are as follows:

Getting Support

Telodendria is designed to be fairly straightforward, but that doesn't mean there won't be hiccups along the way. If you are struggling to get Telodendria up and running, you're more than welcome to reach out for support. Just join the #telodendria-general:bancino.net Matrix channel. Before you do though, make sure you're running the latest version of Telodendria and you've thoroughly read through all the relevant documentation.

Contributing

Telodendria is an open source project. As such, it welcomes contributions. There are many ways you can contribute, and any way you can is greatly appreciated.

Reporting Issues

If—after you've reached out to #telodendria-general:bancino.net—it has been determined that there is a problem with Telodendria, it should be reported to #telodendria-issues:bancino.net. There it can be discussed further. The issues channel serves as the official issue tracker of Telodendria; although issues may be copied into a TODO file in the CVS repository just so they don't get lost.

Developing

The primary language used to write Telodendria code is ANSI C. Yes, that's the original C standard from 1989. The reason this standard is chosen, and the reason that it will not be changed, is because the original C is the most portable. Other languages you'll find in the Telodendria repository are shell scripts and HTML. If you have any experience at all with any of these languages, your contributions are valuable. Please follow the guidelines in this section to ensure the contribution workflow goes as smoothly as possible.

Getting The Code

You can download an official release tarball if you would really like, but the preferred way is to check out the source code from CVS. This makes generating patches a lot easier. If you do not have CVS, consult your operating system's package repository to install it. CVS was the chosen version control system for this project primarily because it is built into OpenBSD.

$ export CVSROOT=anoncvs@bancino.net:/cvs $ cvs checkout Telodendria $ cd Telodendria

You should now have the latest Telodendria source code. Follow the Code Style as you make your changes.

Code Style

Telodendria's code style is very unique. In general, these are the conventions used by the code base.

This guide may be subject to change. The source code is the absolute source of truth, so as long as you make your code look like the code surrounding it, you should be fine.

Submitting Patches

Submitting patches is fairly easy to do if you've got the CVS sources checked out. Once you have made your changes, just run cvs diff:

$ cvs diff -uNp > your-changes.patch

Then, send the resulting patches to #telodendria-patches:bancino.net, where they will be promptly reviewed by the community.

License

All of the code and documentation for Telodendria is licensed under the following terms and conditions:

Copyright (C) 2022 Jordan Bancino <@jordan:bancino.net> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Change Log

At this time, Telodendria does not have any tagged releases because it is not yet functional as a Matrix homeserver. Please check out the Project Status to see where things are currently at.