From 2f22c638938970e5c4dbbab7c79e53ee60e4bdfc Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Thu, 28 Jul 2022 09:57:59 -0400
Subject: [PATCH] Document the configuration file.

Note that we aren't even parsing this yet, but we will soon...
---
 contrib/telodendria.conf | 104 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 100 insertions(+), 4 deletions(-)

diff --git a/contrib/telodendria.conf b/contrib/telodendria.conf
index 8d32a41..fce4853 100644
--- a/contrib/telodendria.conf
+++ b/contrib/telodendria.conf
@@ -1,13 +1,109 @@
+#
 # Telodendria configuration file
+#
+# This example configuration file serves as the authoritative
+# configuration documentation for the version of Telodendria it
+# ships with.
+#
 
+#
+# Basic configuration
+#
+# This section contains the most common configuration items that you
+# should go through and check.
+#
+
+# The address to listen on. You can specify multiple addresses by
+# simply adding more values to this directive. It is recommended
+# to only listen on localhost, and then configure a reverse proxy
+# such as relayd(8) in front of it, because the server does not
+# implement TLS.
+#
+# Also note that Telodendria doesn't provide multiple ports for
+# different things. All APIs are made available over the same port.
+# This works because Matrix allows the port configuration to be
+# shared via .well-known/matrix/, which this server does properly
+# serve.
+listen "localhost:8008";
+
+# 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 change, unless you want to start over.
+server-name "example.com";
+
+# The data directory in which Telodendria will store all user and
+# event information. Telodendria doesn't use a database; it uses a
+# flat-file directory structure, sort of like how most SMTP servers
+# use Maildirs or mbox files.
+data-dir "/var/telodendria";
+
+# Whether to enable federation or not. Matrix is by default
+# a federated protocol, but if you just want your own internal chat
+# system with no contact to the outside, then you can disable
+# federation.
+federation "true";
+
+# Whether to enable new user registration or not. For security and
+# anti-spam reasons, this is set to false. You can add users via the
+# command-line tool. 
+#
+# Generally, everyone should run their own homeserver, but that isn't
+# always possible with the waning number of available public IP
+# addresses, so if you'd like to provide a public service and allow
+# others to register for accounts on your homeserver, feel free to
+# enable registration. Telodendria should be able to handle a large
+# amount of users without difficulty.
+registration "false";
+
+#
+# Advanced options
+#
+# This section contains options for system administrators that need
+# more control over their Telodendria instance.
+#
+
+# Log to a file. If this directive is omitted, logging is done to
+# the system standard output. It may be redirected to the syslog from
+# there, but it may not.
+#
+# Telodendria manages its own log file format, so it manually
+# configures the log file. If you're going to be running Telodendria
+# in a chroot, the log file will have to live inside the chroot.
+#
+# Acceptable values here are "stdout", "stderr", or a log file.
 log "/var/log/telodendria.log" {
+	# The level to log. This can be one of "error", "warning",
+	# "task", "message", or "debug", with each level showing all
+	# the levels above it as well. For example, "error" shows
+	# only errors, "warning" shows warnings and errors, "task"
+	# shows tasks, warnings, and errors, and so on.
 	level "message";
-	timestampFormat "none";
+
+	# If you want to customize the timestamp format, you may do so
+	# here. Acceptable values are "none", "default", or a formatter
+	# string as described by your system's strftime(3). 
+	timestampFormat "default";
+
+	# Whether or not to enable colored output on TTYs. Note that 
+	# color sequences will not be written to a log file, so this
+	# only applies if the log is being written to a real terminal.
 	color "true";
 };
 
+# How many worker threads to spin up and pull from the request queue.
+# This should generally be less than your total CPU core count, to
+# prevent overloading your system, but if you have a multithreaded
+# system, feel free to set this to as many threads as you feel
+# comfortable with Telodendria managing.
+#
+# Note that if you have a single-threaded machine with only 1 CPU
+# core (as is typical with low-tier virtual machines), you may want
+# to set this to a lower number, or even set it to zero to disable
+# threading altogether, and run everything in a main thread,
+# processing requests one at a time.
+#
+# Ultimately, it depends on what your machine is capable of. You may
+# just have to play around with this value to see which configuration
+# gives you the best performance.
 threads "4";
 
-data-dir "/var/telodendria";
-
-federation "true";
\ No newline at end of file