Add admin documentation home page.

This commit is contained in:
Jordan Bancino 2023-09-08 17:22:24 -04:00
parent e4a217550f
commit c78d075a93
6 changed files with 33 additions and 227 deletions

View file

@ -70,7 +70,7 @@ to add support for.
a TLS port and a non-TLS port, for example.
- Moved all program configuration to the data directory and added an administrator
API endpoint to manage it. It is now no longer recommended to manually update the
configuration file. Consult the [Administrator API](user/admin.md) documentation
configuration file. Consult the [Administrator API](user/admin/README.md) documentation
and the [Configuration](user/config.md) documentation.
- Added an administrator API endpoint for process control. Telodendria can now be
restarted or shutdown via API endpoint.
@ -242,4 +242,4 @@ This is the first public release of Telodendria so there are no changes to repor
Future releases will have a complete change log entry here.
This is a symbolic release targeted at developers, so there's nothing useful to
ordinary users yet. Stay tuned for future releases though!
ordinary users yet. Stay tuned for future releases though!

View file

@ -4,6 +4,11 @@ Here you will find all of the documentation for Telodendria. If you
find that some documentation is missing or incorrect, please open an
issue, and, even better, a pull request to fix the issue.
You are also welcome to join the
[`#telodendria-general:bancino.net`](https://matrix.to/#/#telodendria-general:bancino.net)
matrix room, where you can discuss Telodnedria with others and ask
questions.
## User Documentation
- [System Requirements](user/requirements.md)
@ -11,7 +16,7 @@ issue, and, even better, a pull request to fix the issue.
- [Usage & Running](user/usage.md)
- [Initial Set Up](user/setup.md)
- [Configuration Options](user/config.md)
- [Administrator API](user/admin.md)
- [Administrator API](user/admin/README.md)
## Developer Documentation

22
docs/user/admin/README.md Normal file
View file

@ -0,0 +1,22 @@
# Administrator API
Telodendria provides an administrator API as an extension to the
Matrix specification that allows for administrator control over the
homeserver. This includes profiling and examining the state of
running instances, as well as managing users and media.
Like Synapse, Telodendria supports designating specific local users as
administrators. However, unlike Synapse, Telodendria uses a more
fine-grained privilege model that allows a server administrator to
delegate specific administration tasks to other users while not
compromising and granting them full administrative access to the server.
To authenticate with the administrator API, simply use your login
access token just like you would authenticate any other Matrix client
request.
- [Privileges](privileges.md)
- [Configuration](config.md)
- [Server Statistics](stats.md)
- [Process Control(proc.md)

View file

@ -26,7 +26,7 @@ source, execute the binary directly. If needed, consult the
initialize its database directly with a simple—and, importantly,
safe—default configuration, as well as a randomly generated,
single-use registration token that grants a user all privileges
documented in the [Administrator API](admin.md) documentation.
documented in the [Administrator API](admin/README.md) documentation.
Consult the log file for this administrator registration token. By
default, the log file is located in the data directory, and is named
`telodendria.log`.
@ -40,7 +40,7 @@ it also has all privileges granted to it, so it can make full use of
the Administrator API.
1. Using the access token granted for the administrator account via
the login process, configure Telodendria as descibed in
[Configuration](config.md). See the [Administrator API](admin.md)
[Configuration](config.md). See the [Administrator API](admin/README.md)
documentation for the configuration endpoint details.
This is the recommended way to set up Telodendria. However, if you

View file

@ -9,7 +9,7 @@ testing or debugging purposes.
## Command Line Options
Typically, Telodendria is controlled via the
[Administrator API](admin.md), but the Telodendria binary does include
[Administrator API](admin/README.md), but the Telodendria binary does include
a few command line options, which can be used in init scripts or for
debugging purposes.

View file

@ -1,221 +0,0 @@
.Dd $Mdocdate: March 10 2023 $
.Dt TELODENDRIA 7
.Os Telodendria Project
.Sh NAME
.Nm Telodendria
.Nd Start here. This page contains the project introduction, and provides information about it, such as its status, how to contact the developers, and what the source code license is.
.Sh DESCRIPTION
.Nm
is an open source Matrix homeserver written entirely from scratch in ANSI C and
designed to be lightweight and simple, yet functional.
.Pp
.Nm
differentiates itself from the other Matrix homeserver
implementations because it:
.Bl -bullet
.It
Is written in C, a stable, low-level programming language with a
long history, low build and runtime overhead, and wide compatibility.
.It
Is written with minimalism as a primary design goal. Whenever possible
and practical, no third-party libraries are pulled into the source code.
Everything
.Nm
needs is custom written. As a result,
.Nm
depends only on a standard C compiler and a POSIX C library to be built,
both of which should come with any good Unix-style operating system already,
which means you shouldn't have to install anything extra.
.It
Uses a flat-file directory structure to store data instead of a database.
This has a number of advantages:
.Bl -bullet
.It
It makes setup and maintenance much easier.
.It
It allows
.Nm
to run on systems with fewer resources.
.El
.It
Is packaged as a single small, statically-linked and highly-optimized binary
that can be run just about anywhere. It is designed to be extremely easy to
set up and consume as few resources as possible.
.It
Is permissively licensed.
.Nm
is licensed under a modified MIT license, which imposes very few restrictions
on what you can do with it.
.El
.Pp
.Nm
is on Matrix! Check out the official Matrix rooms:
.Pp
.TS
box tab(;);
ll.
#telodendria:bancino.net;The public "space" room.
#telodendria-releases:bancino.net;Get notified of new releases.
#telodendria-general:bancino.net;General discussion and support.
#telodendria-newsletter:bancino.net;Periodic status updates.
#telodendria-issues:bancino.net;Report bugs and issues.
#telodendria-patches:bancino.net;Submit code patches to the project.
#telodendria-ports:bancino.net;Discussion about porting and packaging.
.TE
.Pp
.Nm
is designed to be fairly straightforward, but that doesn't mean there
won't be hiccups along the way. If you're struggling to get
.Nm
up and running, you're more than welcome to reach out for support. Just
hop into the appropriate Matrix rooms and talk to me!
.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.
.Pp
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.
.Pp
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 the project's goals, but it is a list of things that I want to prioritize,
because other server implementations lack them.
.Pp
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 as privacy-friendly as possible.
.Nm
should not store any information it does not absolutely need to function as a
Matrix homeserver. While
.Nm
strives to be feature-complete, it should not implement anything not explicitly
defined in the Matrix specification.
.It
To be a production-ready Matrix server capable of working in constrained environments,
such as embedded devices, cheap VPSs, or a peer-to-peer device.
.Nm
should also work on traditional setups as well, and be able to handle a decent
amount of users. It should work well for personal Matrix homeservers that also
host a few friends and/or family members.
.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
.Pp
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 ,
.Xr td 1
.Sh STANDARDS
The installed version of
.Nm
conforms to the latest Matrix specification available at the time
of its release.
.Sh HISTORY
.Pp
.Nm
was started in early July of 2022. For a change log of this
project, see
.Xr telodendria-changelog 7 .
.Sh AUTHORS
.Nm
was started by and is almost exclusively developed by
Jordan Bancino <@jordan:bancino.net>. Contributions to the code,
website, documentation, or other components of this project have
been made by various open source developers.
.Sh LICENSE
All of the code and documentation for
.Nm
is licensed under a modified MIT license. Please consult the
.Pa LICENSE.txt
file for the actual license text. The
.Nm
license text differs from the MIT license in the following ways:
.Bl -bullet
.It
Where the MIT license states that the copyright notice and permission
notice shall be included in all copies or
.Pa substantial
portions of the software, the
.Nm
license requires the copyright notice and permission notice be included
with
.Pa all
portions, regardless of the size, of the software by omitting the word
.Pa substantial .
.El
.Pp
The
.Nm
logo in all forms, including the ASCII representation, belongs solely
to the
.Nm
project. It must only be used to represent the official
.Nm
project, and may only appear in official
.Nm
media. If
.Nm
is forked, the logo must be removed completely from the project, and
optionally replaced with a different one. The logo may not be modified
in any way or for any purpose.