forked from Telodendria/Telodendria
119 lines
4.4 KiB
Groff
119 lines
4.4 KiB
Groff
.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
|