Add setup documentation.

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)
 

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.
+

man/man7/telodendria-setup.7

@@ -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