From c9963d36b132f4eb602036bb0e90ac7db3d7d362 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 22 Sep 2022 17:29:03 -0400 Subject: [PATCH] Move Rationale and Project Goals to man page. --- docs/telodendria.7 | 88 ++++++++++++++++++++++++++++++++++++ site/index.html | 110 ++------------------------------------------- 2 files changed, 92 insertions(+), 106 deletions(-) diff --git a/docs/telodendria.7 b/docs/telodendria.7 index b005abf..656a493 100644 --- a/docs/telodendria.7 +++ b/docs/telodendria.7 @@ -68,6 +68,94 @@ Room;Description #telodendria-issues:bancino.net;Report bugs and issues. #telodendria-patches:bancino.net;Submit code patches to the project. .TE +.Sh RATIONALE +I want a lightweight Matrix homeserver designed specifically for OpenBSD, +and other Unix-like operating systems. I want a homeserver that can be +developed and compiled with built-in tools. I want it to function entirely +on a base OS install without having to install any packages whatsoever. I've +found that as far as these goals are concerned, the existing homeserver +implementations fall short. This project aims to prove that Matrix homeservers +can be lightweight and written in such a way that very few, if any, third-party +libraries need to be pulled in. +.sp +I also want to learn how Matrix works, and I want to understand the code I'm +running on my server, which is why I'm writing every component from scratch, +even the HTTP server and router. +.sp +The advantage of using a flat-file database instead of a real database is that +your data remains in a format that is incredibly easy to digest. Backups are +incredibly easy as well\(emjust +.Xr tar 1 +up the data directory and you're good to go. +.Sh PROJECT GOALS +The goals of this project are generally divided into user goals and developer +goals, depending on who they impact the most. This isn't an exaustive list +of +.Nm 's +goals, but it is a list of things that I want to prioritize, because other +server implementations lack them. +.sp +The user goals are as follows: +.Bl -bullet +.It +To implement the latest Matrix specification as fully and completely as possible. +All features defined by the specification should eventually be present in +.Nm . +.It +To be a production-ready Matrix server capable of handling a lot of users. +.Nm +should have good performance in many diverse environments. It should scale up +well for large instances, such as the +.Pa matrix.org +instance, and yet also be able to scale down to an embedded or peer-to-peer +device. +.It +To be easier to get up and running, and yet also be more configurable than other +Matrix homeserver implementations. The configuration file should be flexible, +well-documented, and easy to understand and modify. An intuitive command-line +tool for administrative tasks should also be available. +.El +.sp +The developer goals are as follows: +.Bl -bullet +.It +To have as few build and runtime dependencies as possible. It should be possible +to compile and run +.Nm +on any POSIX operating system right out of the box. +.Nm +should be fully statically-linked, so it can run under a +.Xr chroot 3 . +Furthermore, it should be possible to read all the documentation offline, and +without any overly complicated tools. You'll notice that this documentation is +a collection of +.Xr man 1 +pages, not HTML or Markdown, to remove the dependency on a browser or Markdown +parser. Any Unix-like system has a manual page viewer, which makes the +documentation more accessible, even on remote systems that have no graphical +interface to read the documentation. This ensures that you can read the +documentation for the installed version of +.Nm +without having to go online. +.It +To have a simple yet elegant workflow, and not depend on any large or complex +development tools such as code forges. The entire development workflow should +be able to be successfully and efficiently completed on a base OpenBSD install. +Of course, you don't have to use OpenBSD for development, but the point is that +the workflow should require fairly standardized and simple tools. +.It +To write clean, elegant, well-tested, and well-documented code. The goal is to build +a Matrix homeserver from the ground up, not just because I don't like the way existing +homeservers are implemented, but also because I want to learn how Matrix works, +make it more accessible, and potentially teach others a little bit along the way. +.It +To foster a welcoming community. Many big communities such as Linux and OpenBSD +have hostile leaders. +.Nm +shouldn't have a hostile leader. I want to be as understanding as I can, and talk +through issues politely and in a civil manner. If I'm failing in this way, don't +be afraid to call me out! +.El .Sh SEE ALSO .Xr telodendria 8 , .Xr telodendria.conf 5 , diff --git a/site/index.html b/site/index.html index 5ebb782..b39f59f 100644 --- a/site/index.html +++ b/site/index.html @@ -171,14 +171,14 @@ You can check out the change log here.

Telodendria's documentation is distributed with the source code as man pages, which contain all of the information -on how to build the source, configure it, as well as contribute to -the project. The man pages are also available online -for convenience: +on what Telodendria is, what its goals are, how to build the source, +configure it, as well as contribute to the project. The man +pages are also available online for convenience:

Project Status

@@ -358,108 +358,6 @@ on my list for that:
  • Add other message divs for notes and warnings.
    • -

    Rationale

    -

    -I want a lightweight Matrix homeserver designed specifically for -OpenBSD and other Unix-like operating systems. I want a homeserver -that can be developed and compiled with built-in tools. I want it -to function entirely on a base OS -install without having to install any extra packages whatsoever. -I've found that as far as these goals are concerned, the -existing homeserver implementations fall short. This -project aims to prove that Matrix homeservers can be lightweight and -written in such a way that very few, if any, third-party libraries -need to be pulled in. -

    -

    -I also want to learn how Matrix works, and I want to understand the -code I'm running on my server, which is why I'm writing every -component from scratch, even the HTTP server. -

    -Telodendria is written entirely in portable ANSI C. It depends on -no third-party C libraries other than the standard POSIX C library. -The only thing you need to run it is a reverse proxy with HTTPS support, -such as relayd(8), 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. This makes it suitable for running -in a chroot(8) environment. -

    -

    -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 just run on any POSIX operating system without modification. -

    -

    Project Goals

    -

    -The goals of this project are generally divided into user goals, -and developer goals, depending on who they impact the most. This -isn't an exhaustive list, but it is a list of things that I want to -prioritize, because other server implementations lack them. -

    -

    -The user goals are as follows: -

    - -

    -The developer goals are as follows: -

    -

    Getting Support

    Telodendria is designed to be fairly straightforward, but that