forked from lda/telodendria
Move Rationale and Project Goals to man page.
This commit is contained in:
parent
bbf8f26889
commit
c9963d36b1
|
@ -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
110
site/index.html
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue