forked from Telodendria/Telodendria
Add admin documentation home page.
This commit is contained in:
parent
e4a217550f
commit
c78d075a93
6 changed files with 33 additions and 227 deletions
|
|
@ -70,7 +70,7 @@ to add support for.
|
||||||
a TLS port and a non-TLS port, for example.
|
a TLS port and a non-TLS port, for example.
|
||||||
- Moved all program configuration to the data directory and added an administrator
|
- 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
|
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.
|
and the [Configuration](user/config.md) documentation.
|
||||||
- Added an administrator API endpoint for process control. Telodendria can now be
|
- Added an administrator API endpoint for process control. Telodendria can now be
|
||||||
restarted or shutdown via API endpoint.
|
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.
|
Future releases will have a complete change log entry here.
|
||||||
|
|
||||||
This is a symbolic release targeted at developers, so there's nothing useful to
|
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!
|
||||||
|
|
|
||||||
|
|
@ -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
|
find that some documentation is missing or incorrect, please open an
|
||||||
issue, and, even better, a pull request to fix the issue.
|
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
|
## User Documentation
|
||||||
|
|
||||||
- [System Requirements](user/requirements.md)
|
- [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)
|
- [Usage & Running](user/usage.md)
|
||||||
- [Initial Set Up](user/setup.md)
|
- [Initial Set Up](user/setup.md)
|
||||||
- [Configuration Options](user/config.md)
|
- [Configuration Options](user/config.md)
|
||||||
- [Administrator API](user/admin.md)
|
- [Administrator API](user/admin/README.md)
|
||||||
|
|
||||||
## Developer Documentation
|
## Developer Documentation
|
||||||
|
|
||||||
|
|
|
||||||
22
docs/user/admin/README.md
Normal file
22
docs/user/admin/README.md
Normal 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)
|
||||||
|
|
||||||
|
|
@ -26,7 +26,7 @@ source, execute the binary directly. If needed, consult the
|
||||||
initialize its database directly with a simple—and, importantly,
|
initialize its database directly with a simple—and, importantly,
|
||||||
safe—default configuration, as well as a randomly generated,
|
safe—default configuration, as well as a randomly generated,
|
||||||
single-use registration token that grants a user all privileges
|
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
|
Consult the log file for this administrator registration token. By
|
||||||
default, the log file is located in the data directory, and is named
|
default, the log file is located in the data directory, and is named
|
||||||
`telodendria.log`.
|
`telodendria.log`.
|
||||||
|
|
@ -40,7 +40,7 @@ it also has all privileges granted to it, so it can make full use of
|
||||||
the Administrator API.
|
the Administrator API.
|
||||||
1. Using the access token granted for the administrator account via
|
1. Using the access token granted for the administrator account via
|
||||||
the login process, configure Telodendria as descibed in
|
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.
|
documentation for the configuration endpoint details.
|
||||||
|
|
||||||
This is the recommended way to set up Telodendria. However, if you
|
This is the recommended way to set up Telodendria. However, if you
|
||||||
|
|
|
||||||
|
|
@ -9,7 +9,7 @@ testing or debugging purposes.
|
||||||
## Command Line Options
|
## Command Line Options
|
||||||
|
|
||||||
Typically, Telodendria is controlled via the
|
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
|
a few command line options, which can be used in init scripts or for
|
||||||
debugging purposes.
|
debugging purposes.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
|
||||||
Loading…
Reference in a new issue