telodendria/man/man7/porting.7

.Dd $Mdocdate: April 24 2023 $
.Dt PORTING 7
.Os Telodendria Project
.Sh NAME
.Nm porting
.Nd Some guidelines for packaging Telodendria for your operating system.
.Sh DESCRIPTION
.Pp
Telodendria is distributed at source code, and does not offer a
convenient install process. This is intentional; the Telodendria
project is primarily concerned with developing Telodendria itself,
not packaging it for the hundreds of different operating systems
and Linux distributions that exist.  It is my firm belief that
distributing an open source project is not the job of the open
source developer; that's the reason software distributions exist,
to collect and distribute software.
.Pp
It would be impossible to single-handedly package Telodendria for
every platform, because each platform has very different expectations
for software. Even different Linux distributions have different
conventions for where manual pages, binaries, and configuration
files go.
.Pp
That being said, this page aims to assist those who want to package
Telodendria for their operating system or software distribution.
.Pp
See
.Xr td 1
for instructions on how to build Telodendria. Only proceed with
packaging Telodendria after you have successfully built it on your
operating system.
.Pp
To package Telodendria, you should collect the following files, and
figure out where they should be installed for your system:
.Bl -bullet
.It
The telodendria server binary itself:
.Pa build/telodendria
.It
All manual pages in the
.Pa man/
directory that are prefixed with "telodendria". These are the user
documentation pages. All pages that do not have the "telodendria"
prefix are intended only for developers, and so do not need to be
installed to the system.
.It
An init script. People that wish to install Telodendria to their
system expect it to be integrated enough that Telodendria can be
easily started at boot, and otherwise managed by the system's daemon
tools, be it systemd, or another init system. Consult your system's
documentation for writing an init script. Do note that Telodendria
does not fork itself to the background; the init script should do
that. Note that the init script probably requires a few things:
.Bl -bullet
.It
A dedicated system user under which Telodendria should run.
Telodendria can either be started as that user, or started as
root and configured to automatically drop to that user.
.It
A default data directory, in which all Telodendria data, including
the configuration and logs, will be stored. A good default on
Unix-like system is probably
.Pa /var/telodendria .
.El
.El
.Pp
Optionally, it may be helpful to provide these as well:
.Bl -bullet
.It
A sample Telodendria configuration. This should be placed in the
examples directory on your
system, if such a directory exists. You can use or adapt any of the
configuration files in
.Pa contrib/ ,
or write your own specifically for your package.
.El
.Pp
Once you have collected the files that need to be installed, make
sure your package performs the following tasks on install:
.Bl -bullet
.It
If necessary, depending on the config used, create a new system
user for the Telodendria daemon to run as.
.It
If conventional for your system, enable the Telodendria init script
so that Telodendria is started on system boot.
.It
Insruct the user to carefully read the
.Xr telodendria-setup 7 ,
.Xr telodendria-admin 7 ,
and
.Xr telodendria-config 7
manual pages before starting Telodendria.
.El
.Pp
The goal of a package should be to get everything as ready-to-run
as possible.  The user should be able to start Telodendria
right away and begin configuring it.
.Pp
Remember to publicly document the setup of Telodendria on your
platform so that users can easily get things running. If you're
packaging Telodendria for a containerization system such as Docker,
you can omit the things that containers typically do not have, such
as the init script and man pages.
.Pp
Also remember that your port should feel like it belongs on your
target system.  Follow all of your system's conventions when placing
files on the filesystem, so your users know what to expect. The
goal is not necessarily to have a unified experience across all
operating systems, rather, you should cater to the opinions of
your operating system. Telodendria is architected in such a way
that it does not impose the developers opinions of where things
should go, and since the configuration lives in the database,
it is fairly self-contained.
.Pp
.Sh SEE ALSO
.Xr telodendria-contributing 7 ,
.Xr td 1 ,
.Xr telodendria 7