From c78d075a93336942db63672fd003f6638187ae21 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 17:22:24 -0400 Subject: [PATCH] Add admin documentation home page. --- docs/CHANGELOG.md | 4 +- docs/README.md | 7 +- docs/user/admin/README.md | 22 ++++ docs/user/setup.md | 4 +- docs/user/usage.md | 2 +- man/man7/telodendria.7 | 221 -------------------------------------- 6 files changed, 33 insertions(+), 227 deletions(-) create mode 100644 docs/user/admin/README.md delete mode 100644 man/man7/telodendria.7 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 151ba19..15bb2ce 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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! \ No newline at end of file +ordinary users yet. Stay tuned for future releases though! diff --git a/docs/README.md b/docs/README.md index 248f5fe..6d004b4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/user/admin/README.md b/docs/user/admin/README.md new file mode 100644 index 0000000..39f00d5 --- /dev/null +++ b/docs/user/admin/README.md @@ -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) + diff --git a/docs/user/setup.md b/docs/user/setup.md index ac0ebdf..ac1e336 100644 --- a/docs/user/setup.md +++ b/docs/user/setup.md @@ -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 diff --git a/docs/user/usage.md b/docs/user/usage.md index 8fcd604..838cc5d 100644 --- a/docs/user/usage.md +++ b/docs/user/usage.md @@ -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. diff --git a/man/man7/telodendria.7 b/man/man7/telodendria.7 deleted file mode 100644 index 9dee9dc..0000000 --- a/man/man7/telodendria.7 +++ /dev/null @@ -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.