From dc0a62efcf71a1c3455546843c3e820d618a0174 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Mon, 10 Oct 2022 21:06:59 -0400 Subject: [PATCH] Add onboarding --- TODO.txt | 12 ++-- man/man7/onboarding.7 | 134 ++++++++++++++++++++++++++++++++++++++++++ man/man8/td.8 | 7 ++- site/index.html | 7 +++ 4 files changed, 152 insertions(+), 8 deletions(-) create mode 100644 man/man7/onboarding.7 diff --git a/TODO.txt b/TODO.txt index 0565628..52a1766 100644 --- a/TODO.txt +++ b/TODO.txt @@ -43,7 +43,7 @@ Phase 2: Building a foundation [ ] Figure out how to write unit tests for array/hashmap/etc [x] Parse the Telodendria config file [x] Add license header to all files -[ ] Add documentation for all public APIs +[!] Add documentation for all public APIs (See below) [x] Implement a simple HTTP server [ ] Implement param parser [x] URL encoder/decoder @@ -53,6 +53,8 @@ Phase 2: Building a foundation [ ] Data abstraction layer [x] Error generation [x] Properly implement the command line options as stated in telodendria(8) +[ ] Remove "chroot" option, just chroot into the data dir, and make the log + file live there as well. Phase 3: Welcome to Matrix @@ -122,8 +124,6 @@ Documentation [ ] TelodendriaConfig [ ] Util -[ ] Add onboarding documentation - [ ] Building from source - [ ] Writing config file - [ ] Setting up chroot - [ ] Setting up relayd +[x] Add onboarding documentation + [x] Building from source + [!] Writing config file (see Config.5) diff --git a/man/man7/onboarding.7 b/man/man7/onboarding.7 new file mode 100644 index 0000000..d9edd85 --- /dev/null +++ b/man/man7/onboarding.7 @@ -0,0 +1,134 @@ +.Dd $Mdocdate: October 11 2022 $ +.Dt ONBOARDING 7 +.Os Telodendria Project +.Sh NAME +.Nm onboarding +.Nd Guide to getting Telodendria running on your system. +.Sh DESCRIPTION +This page aims to provide a high-level overview of how to +get Telodendria running on your system from source. It assumes +that you're running OpenBSD, or know how to translate OpenBSD +commands into your system's commands, and that you are using an +an official distribution tarball. If you are using your system's +package manager to install Telodendria, you should refer to the +package maintainer's installation instructions instead of these +instructions. +.Pp +If you're a package maintainer, or would like to be, these +instructions might also be helpful for you as well; you can +use them to learn how the process is designed to work, so you +can mimic it on your system. +.Sh PREREQUISITES +To build Telodendria, you just need a POSIX system and C compiler. +If your system does not ship with a C compiler, please install +one before continuing with these directions. +.Pp +The build script relies on a POSIX shell implementation, as well +as the standard userspace utilities specified by POSIX. +.Pp +This should be obvious, but you'll also need a way to +download files to your machine, or otherwise copy them into place. +You'll also need +.Xr tar 1 , +and +.Xr gzip 1 +to extract the downloaded tarball. +.Sh GETTING THE CODE +You can download the source code for Telodendria by going to +the official website and downloading a tarball from the table. +Otherwise, you can download the tarball and supplemental files +directly: +.Bd -literal -offset indent +$ export VERSION=x.x.x # Set version of Telodendria you want +$ ftp https://telodendria.io/pub/v$VERSION/Telodendria-v$VERSION.tar.gz +$ ftp https://telodendria.io/pub/v$VERSION/Telodendria-v$VERSION.tar.gz.{sha256,sig} +.Ed +.Pp +Before you extract the tarball, it is a good idea to verify both its checksum +and its signature. Use +.Xr sha256 1 +to verify that the download was not corrupted in transit: +.Bd -literal -offset indent +$ sha256 -C Telodendria-v$VERSION.tar.gz.sha256 Telodendria-v$VERSION.tar.gz +.Ed +.Pp +Use +.Xr signify 1 +to verify that the download was legitimately published by the Telodendria +project: +.Bd -literal -offset indent +$ signify -V -p telodendria-signify.pub -m Telodendria-v$VERSION.tar.gz +.Ed +.Pp +You can obtain +.Pa telodendria-signify.pub +from the official website. While you may absolutely obtain the tarball +and checksum files from mirrors or other sources, do not obtain the public +key file from any other sources than the official website. Downloads from +other sources should be verified by the official public key only: +.Bd -literal -offset indent +$ ftp https://telodendria.io/telodendria-signify.pub +.Ed +.Pp +Finally, only when the tarball is verified, you can extract it: +.Bd -literal -offset indent +$ tar -xzf Telodendria-v$VERSION.tar.gz +$ cd Telodendria-v$VERSION +.Ed +.Sh BUILDING AND INSTALLING +In the source directory, just run the following commands: +.Bd -literal -offset indent +$ . tools/env.sh +$ td build +$ doas td install +.Ed +.Pp +This will compile the code, and install the output binary, along +with all of the documentation and configuration files, to the system. +.Pp +.Sy Packagers: +It might be beneficial to take a look at the install recipe in the +.Xr td 8 +script so you know what files go where. Adapt the general procedure +for your operating system. +.Sh CONFIGURATION +A sufficiently complete configuration file should have been installed +to +.Pa /etc/telodendria.conf . +Open it with your preferred editor, and go through each line, making +sure everything is set appropriately for your setup. Consult the +.Xr telodendria.conf 5 +and +.Xr Config 5 +pages for a comprehensive list of all the available options and a +description for each option, as well as the general syntax of the +configuration file. You'll most certainly have to set your +server's name and base URL. Optionally, specify an identity server, +and whether or not you want to enable federation and registration. +All other options should have sane defaults for most systems. +.Sh STARTING TELODENDRIA +Once you've written the configuration file, it should just be as +easy as starting the +.Dv telodendria +daemon: +.Bd -literal -offset indent +$ rcctl enable telodendria +$ rcctl start telodendria +.Ed +.Pp +It might be a good idea to check the log file to make sure everything +started okay and is running fine. +.Pp +At this point, it would be a very good idea to configure a reverse +proxy. The +.Pa contrib/ +directory of the source code has an example +.Xr relayd.conf 5 +file which can be installed as-is into the typical location, or +integrated into an existing configuration. At some point in the +future, a reverse proxy may not be required for TLS, but it will +always be recommended because it provides more control and security. +.Sh SEE ALSO +.Xr td 8 , +.Xr telodendria.conf 5 , +.Xr telodendria 8 diff --git a/man/man8/td.8 b/man/man8/td.8 index 795f7d5..3fdb7c9 100644 --- a/man/man8/td.8 +++ b/man/man8/td.8 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: September 30 2022 $ +.Dd $Mdocdate: October 11 2022 $ .Dt TD 8 .Os Telodendria Project .Sh NAME @@ -234,5 +234,8 @@ executed each time is invoked. .Sh EXIT STATUS .Sh HISTORY -.Sh CAVEATS .Sh BUGS +.Nm +unconditionally exits with code 0, even if errors occurred. Furthermore, +recipes are run unconditionally, regardless of whether or not any recipes +before have failed. diff --git a/site/index.html b/site/index.html index 5dab174..27b6801 100644 --- a/site/index.html +++ b/site/index.html @@ -57,6 +57,13 @@ pages are also available online for convenience: information about it, such as its status, how to contact the developers, and what the source code license is. + + +onboarding(7) + +Setup instructions for OpenBSD. + + telodendria(8)