forked from lda/telodendria
135 lines
4.8 KiB
Groff
135 lines
4.8 KiB
Groff
|
.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
|