.Dd $Mdocdate: November 6 2022 $
.Dt TELODENDRIA-SETUP 7
.Os Telodendria Project
.Sh NAME
.Nm telodendria-setup
.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