plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Move Rationale and Project Goals to man page.

Browse source
This commit is contained in:
Jordan Bancino 2022-09-22 17:29:03 -04:00
parent bbf8f26889
commit c9963d36b1
2 changed files with 92 additions and 106 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
docs/telodendria.7
View file

@ -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 ,

110
site/index.html
View file

@ -171,14 +171,14 @@ You can check out the change log <a href="#change-log">here</a>.
<p>
<b>Telodendria</b>'s documentation is distributed with the source
code as <code>man</code> pages, which contain all of the information
on how to build the source, configure it, as well as contribute to
the project. The <code>man</code> pages are also available online
for convenience:
on what <b>Telodendria</b> is, what its goals are, how to build the source,
configure it, as well as contribute to the project. The <code>man</code>
pages are also available online for convenience:
</p>
<ul>
<li><a href="telodendria.7.html">telodendria(7)</a> - Introduction</li>
<li><a href="telodendria.8.html">telodendria(8)</a> - Command line</li>
<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration</li>
<li><a href="telodendria.conf.5.html">telodendria.conf(5)</a> - Configuration file</li>
<li><a href="td.8.html">td(8)</a> - Build script and patch instructions</li>
</ul>
<h2 id="project-status">Project Status</h2>
@ -358,108 +358,6 @@ on my list for that:
</li>
<li>Add other message <code>div</code>s for notes and warnings.</li>
</ul>
<h2 id="rationale">Rationale</h2>
<p>
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.
</p>
<p>
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.
</p>
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 <code>relayd(8)</code>, 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 <code>chroot(8)</code> environment.
</p>
<p>
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
<code>tar(1)</code> up the directory, and you're good to go.
</p>
<p>
Telodendria is developed and tested on OpenBSD, but you'll find that it
should just run on any POSIX operating system without modification.
</p>
<h2 id="project-goals">Project Goals</h2>
<p>
The goals of this project are generally divided into <i>user goals</i>,
and <i>developer goals</i>, 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, <i>because other server implementations lack them</i>.
</p>
<p>
The user goals are as follows:
</p>
<ul>
<li>
To implement the latest Matrix specification as fully and completely as
possible. All features should eventually be present in <b>Telodendria</b>.
<li>
To be a production-ready Matrix server capable of handling a lot of
users. Telodendria should have good performance in many diverse
environments. It should scale up well for large instances, and yet also
be able to scale down to a peer-to-peer device.
</li>
<li>
To be easier to configure than any of the 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.
</li>
</ul>
<p>
The developer goals are as follows:
</p>
<ul>
<li>
To have as few external build and run dependencies as possible. It
should be possible to compile Telodendria on any POSIX operating
system right out of the box, and have it be totally statically linked,
ready to run under a <code>chroot(8)</code>. You'll even notice that
the documentation is written in HTML directly, not Markdown, to remove
the dependency on a Markdown parser and renderer.
</li>
<li>
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 by any means, but the point is, the workflow
should not require a lot of tools.
<li>
To be written in 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 so I can learn how Matrix really works, and maybe even teach
others along the way.
</li>
<li>
To foster a welcoming community environment. Many of the big communities
such as Linux and OpenBSD have fairly hostile leaders. <b>Telodendria</b>
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!
</li>
</ul>
<h2 id="getting-support">Getting Support</h2>
<p>
<b>Telodendria</b> is designed to be fairly straightforward, but that