Add some more user documentation to clarify how configuration works.

TODO.txt

@@ -77,8 +77,8 @@ Milestone: v0.3.0
     [ ] HttpRouter
     [ ] Str
     [x] telodendria-admin
-    [ ] telodendria-setup
+    [x] telodendria-setup
-    [ ] telodendria-config
+    [x] telodendria-config
     [ ] Refactor dev pages so function description and
         return value are in the same location.
 

man/man7/telodendria-admin.7

@@ -1,4 +1,4 @@
-.Dd $Mdocdate: April 19 2023 $
+.Dd $Mdocdate: April 20 2023 $
 .Dt TELODENDRIA-ADMIN 7
 .Os Telodendria Project
 .Sh NAME
@@ -290,7 +290,7 @@ lfB lfB lfB
 l l l.
 Field;Type;Description
 restart_required;Boolean;T{
-Whether or not the process needs to be restart to finish applying the
+Whether or not the process needs to be restarted to finish applying the
 configuration. If this is true, the restart endpoint may be used.
 T}
 .TE

man/man7/telodendria-config.7

@@ -1,44 +1,61 @@
-.Dd $Mdocdate: February 15 2023 $
+.Dd $Mdocdate: April 20 2023 $
-.Dt TELODENDRIA.CONF 5
+.Dt TELODENDRIA-CONFIG 7
 .Os Telodendria Project
 .Sh NAME
-.Nm telodendria.conf
+.Nm telodendria-config
-.Nd Configuration file for Telodendria.
+.Nd Telodendria configuration.
 .Sh DESCRIPTION
-.Nm
+.Pp
-is the configuration file for the Telodendria homeserver,
+Telodendria is designed to be configurable. It is configured using
-.Xr telodendria 8 .
+JSON, which is intended to be submitted via the administrator API.
-Telodendria is designed to be extremely configurable. As such,
+This page documents Telodendria's configuration JSON format, which
-it has a fairly extensive configuration file. The configuration
+is used both in the administrator API, and on the disk in the
-file can be passed to the Telodendria binary with the
+database. The configuration file on the disk in the database is
-.Sy -f
+.Pa config.json ,
-option, and is typically located at
+though that file should not be edited directly. Use the API described
-.Pa /etc/telodendria.conf
+in
-.sp
+.Xr telodendria-admin 7
-.Nm
+instead.
-uses JSON for its configuration file syntax, which should be
-familiar. Very early versions of
-.Nm
-used a  custom OpenBSD-style configuration file, but this was
-not as versatile or familiar as JSON.
 .Sh DIRECTIVES
 Here are the top-level directives:
 .Bl -tag -width Ds
-.It Ic listen Ar port
+.It Ic listen Ar listenArr
-The port to listen on. Telodendria will bind to all interfaces, but it
+An array of listener description objects. Telodendria supports
-is recommended to configure your firewall so that it only listens on
+listening on multiple ports, and each port is configured
-localhost, and then configure a reverse proxy such as
+independently of the others. A listener description object looks
-.Xr relayd 8
+like this:
-in front of it, because Telodendria does not implement TLS. Note that
+.Bl -tag -width Ds
-Telodendria doesn't provide multiple ports for the various services it
+.It Ic port Ar port
-offers. ALl APIs are made available over the same port, so care should
+The port to listen on. Telodendria will bind to all interfaces, so it
-be taken in
+is recommended to configure your firewall so you can control what is
-.Xr relayd.conf 5
+allowed to access the Telodendria ports. Note that
-to ensure that only the public Matrix API paths are made available over
+Telodendria offers all APIs over each port; there is no way to
-the internet.
+control which APIs are available over which ports, although all
+APIs should be safe against attacks, so this should not be a
+major concern.
+.Pp
 .Ar port
-should be a decimal port number. This directive is entirely optional. If
+should be a decimal port number. This directive is required. Common
-it is omitted, then Telodendria will listen on port 8008 by default.
+port numbers are 8008 for non-TLS, and 8448 for TLS.
+.It Ic tls Ar tlsObj|null|false
+Telodendria can be compiled with TLS support. If it is, then a
+particular listener can be set to use TLS for connections. If
+.Ic tls
+is not
+.Ar null
+or
+.Ar false ,
+then it can be an object with the following directives:
+.Bl -tag -width Ds
+.It Ic cert Ar file
+A certificate file in the format native to the platform's TLS
+library. This can be an absolute path, otherwise it is relative
+to the data directory.
+.It Ic key Ar file
+A key file in the format native to the platform's TLS library.
+It follows the same rules as the certificate file.
+.El
+.El
 .It Ic serverName Ar name
 Configure the domain name of your homeserver. Note that Matrix servers
 cannot be migrated to other domains, so once this is set, it should never
@@ -91,15 +108,6 @@ specified, then the value of
 .Ic uid
 is copied.
 .El
-.It Ic dataDir Ar directory
-The data directory into which Telodendria will write all user and event
-information. Telodendria doesn't use a database like other Matrix homeserver
-implementations; it uses a flat-file directory structure, similar to how an
-SMTP server uses Maildirs to deliver email. This directive is required.
-.Pp
-Telodendria will
-.Xr chroot 2
-into this directory as soon as possible for security reasons. If the
 .Ic log
 directive is configured to write to a file, the log file will be written
 in the data directory.
@@ -122,7 +130,7 @@ everyone would run their own homeserver, so no public registration would ever
 be required. Unfortunately, not everyone has the means to run their own homeserver,
 especially because of the fact that public IPv4 addresses are becoming increasingly
 harder to come by. If you would like to provide a service to those that are unable
-to run their own homeserver, you can aset this to
+to run their own homeserver, you can set this to
 .Ar true ,
 which will allow anyone to create an account. Telodendria should be capable of handling
 a large amount of users without difficulty or security issues. This directive is
@@ -137,8 +145,7 @@ The lot output destination. If set to
 .Ar file ,
 Telodendria will log to
 .Pa telodendria.log
-inside the
+inside the data directory.
-.Ic dataDir .
 .It Ic level Ar error|warning|notice|message|debug
 The level of messages to log at. Each level shows all the levels above it. For
 example, setting the level to
@@ -178,7 +185,7 @@ machine running Telodendria, so you may just have to play around with different
 values here to see which gives the best performance.
 .It Ic maxConnections Ar count
 The maximum number of simultanious connections to allow to the daemon. This option
-prevents the daemon from allocating large amounts of memory in the even that it
+prevents the daemon from allocating large amounts of memory in the event that it
 undergoes a denial of service attack. It typically does not need to be adjusted.
 .It Ic maxCache Ar bytes
 The maximum size of the cache. Telodendria relies heavily on caching to speed
@@ -190,20 +197,22 @@ minimal memory available.
 .El
 .Sh FILES
 .Bl -tag -width Ds
-.It Pa /etc/telodendria.conf
+.It Pa config.json
-The default
+The configuration file stored on the filesystem in the data
-.Xr telodendria 8
+directory. It is not recommended to edit this directly.
-configuration file.
 .It Pa /var/telodendria
 The recommended data directory.
 .El
 .Sh EXAMPLES
-Please consult the default
+.Pp
-.Nm
+A number of example configuration files are shipped with
-that ships with Telodendria for a complete example. If you installed Telodendria
+Telodendria's source code. They can be found in the
-as a package, then the example should be located at the default location. If you
-are building from source, you can find the default config in the
 .Pa contrib/
-directory.
+directory if you are viewing the source code directly. Otherwise,
+if you installed Telodendria as a package, it is possible that the
+example configurations were placed in the default locations for
+such files on your operating system.
 .Sh SEE ALSO
+.Xr telodendria-setup 7 ,
+.Xr telodendria-admin 7
 .Xr telodendria 8

man/man7/telodendria-setup.7

@@ -0,0 +1,75 @@
+.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