From f6c54cbc7f442ddf295e9cfd88c7d4bc31e24cdd Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Fri, 8 Sep 2023 11:58:54 -0400 Subject: [PATCH] Add setup documentation. --- docs/README.md | 2 +- docs/user/setup.md | 60 +++++++++++++++++++++++++++++ man/man7/telodendria-setup.7 | 75 ------------------------------------ 3 files changed, 61 insertions(+), 76 deletions(-) create mode 100644 docs/user/setup.md delete mode 100644 man/man7/telodendria-setup.7 diff --git a/docs/README.md b/docs/README.md index e927e8f..801b57d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ issue, and, even better, a pull request to fix the issue. - [System Requirements](user/requirements.md) - [Install](user/install.md) - [Usage & Running](user/usage.md) -- [Set Up](user/setup.md) +- [Initial Set Up](user/setup.md) - [Configuration Options](user/config.md) - [Administrator API](user/admin.md) diff --git a/docs/user/setup.md b/docs/user/setup.md new file mode 100644 index 0000000..ac0ebdf --- /dev/null +++ b/docs/user/setup.md @@ -0,0 +1,60 @@ +# Initial Set Up + +While Telodendria strives to be extremely simple to deploy and run, +in most circumstances a few basic setup steps will be necessary. +Telodendria does not have a traditional configuration file like most +daemons. Instead, its configuration lives in its database; as such, +all configuration happens through the administrator API. This design +decision makes Telodendria extremely flexible, because it is possible +to re-configure Telodendria without having to manually edit files on +the filesystem, thus allowing administrators to secure their server +better. + +Please follow the instructions followed here carefully in the order +they are presented for the best results. + +This document assumes that you have installed Telodendria using any +of the instructions found in [Install](install.md). After installation, +follow these steps: + +1. Start Telodendria. If you installed it via a package or container, +consult your operating system or container system's documentation. If +you are running Telodendria from a release binary or have built it from +source, execute the binary directly. If needed, consult the +[Usage](usage.md) page for details on how to run Telodendria. +1. Assuming that Telodendria started properly, it will spin up and +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. +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`. +1. Use the registration token to register for an account on the +server. This account will be the administrator account. You can do this +using the client of your choice, or using tools such as `curl` or +`http`, following the Matrix specification for registering accounts. +The administrator account behaves just like a normal local account +that an ordinary user would have registered on the server, except that +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) +documentation for the configuration endpoint details. + +This is the recommended way to set up Telodendria. However, if you +wish to bypass the account creation step and want to configure +Telodendria by directly writing a configuration file instead of using +the administrator API, you can manually create the configuration file +in the database before starting Telodendria. Simply create `config.json` +following the description in [Configuration](config.md), then start +Telodendria. + +While this alternative method may seem simpler and more convenient +to some administrators, it is only so in the short-term. Note that this +method is not supported, because it gives no access to the +administrator API whatsoever, unless you manually modify the database +further to give a user admin privileges, which is error-prone and +bypasses some of Telodendria's safety mechanisms. + diff --git a/man/man7/telodendria-setup.7 b/man/man7/telodendria-setup.7 deleted file mode 100644 index e49456a..0000000 --- a/man/man7/telodendria-setup.7 +++ /dev/null @@ -1,75 +0,0 @@ -.Dd $Mdocdate: April 20 2023 $ -.Dt TELODENDRIA-SETUP 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-setup -.Nd First-time setup instructions for Telodendria. -.Sh DESCRIPTION -.Pp -While Telodendria strives to be extremely simple to deploy, in most -circumstances a few basic setup steps will be necessary. Telodendria -does not have a traditional configuration file like most daemons. -Instead, its configuration lives in its database; as such, all -configuration happens through the administrator API. This design -decision makes Telodendria extremely flexible, because it is possible -to re-configure Telodendria without having to manually edit files -on the filesystem. It is also why the setup instructions provided -here are in the order they are. Please follow them carefully for the -best results. -.Pp -This page assumes that you have installed Telodendria in the way -prescribed by your operating system. Immediately following installation, -perform these steps, in this order: -.Bl -enum -width Ds -.It -Start Telodendria. Consult your operating system's documentation. If -you are running Telodendria directly from the source code directory, -use -.Xr td 8 . -.It -Assuming Telodendria started properly, it will spin up and initialize -its database directory with a simple\(emand importantly, -safe\(emdefault configuration, and a randomly-generated, single-use -registration token that grants a user all privileges documented in -.Xr telodendria-admin 7. -Consult the log file for this administrator registration token. The -log file is located in the data directory, and is named -.Pa telodendria.log . -.It -Use the registration token to register the administrator account. You -can do this using the client of your choice, or using tools such as -.Xr curl 1 -or -.Xr http 1 . -The administrator account functions just like a normal local account, -except that it has all privileges granted to it, so it can make full -use of the administrator API. -.It -Using the access token for the administrator account, authenticate -with the administrator API and configure Telodendria as described -in -.Xr telodendria-config 7. -See -.Xr telodendria-admin 7 -for the configuration endpoint details. -.El -.Pp -This is the recommended way to set up Telodendria. However, if you -wish to bypass the account creation step, and want to configure -Telodendria by directly writing a configuration file instead of using -the administrator API, you can manually create the configuration file -in the database before starting Telodendria. Simply create -.Pa config.json -following the description in -.Xr telodendria-config 7 , -then start Telodnedria. -.Pp -While this alternative method may seem simpler and more convenient to -some administrators, it is only so in the short-term. Note that this -method is not supported, because it gives no access to the -administrator API whatsoever, unless you manually modify the database -to give a user admin privileges, which is error-prone and bypasses -some of Telodendria's safety mechanisms. -.Sh SEE ALSO -.Xr telodendria-admin 7 , -.Xr telodendria-config 7