Add onboarding

This commit is contained in:
Jordan Bancino 2022-10-10 21:06:59 -04:00
parent 96ecbcbd8a
commit dc0a62efcf
4 changed files with 152 additions and 8 deletions

View file

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

134
man/man7/onboarding.7 Normal file
View file

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

View file

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

View file

@ -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.
</td>
</tr>
<tr>
<td><a href="man/man7/onboarding.7.html">onboarding(7)</a></td>
<td>
Setup instructions for OpenBSD.
</td>
</tr>
<tr>
<td><a href="man/man8/telodendria.8.html">telodendria(8)</a></td>
<td>