Add porting instructions.

This commit is contained in:
Jordan Bancino 2023-09-07 21:53:22 -04:00
parent 93e6582db5
commit 3cb04417ff
3 changed files with 94 additions and 192 deletions

94
docs/dev/ports.md Normal file
View file

@ -0,0 +1,94 @@
## Ports
Telodendria is distributed primarily as source code, and the project
itself does not offer a convenient install process such as in the form
of a shell script. 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
is the reason software distributions exist: to collect and
*distribute* software.
It would be impossible to single-handedly package Telodendria for
every platform, because each platform has very different expectations
and conventions for software. Even different Linux distributions have
different conventions for where manual pages, binaries, and
configuration files go.
That being said, this document aims to assist those who want to
package Telodendria for their operating system or software
distribution.
---
Before attempting to package Telodendria, make sure that you can build
it and that it builds cleanly on your target platform. See
[Install → From Source](../user/install.md#from-source)
for general build instructions.
To package Telodendria, you should collect the following files, and
figure out where they should be installed on your system:
- The `telodendria` server binary itself, located at
`build/telodendria`.
- All manual pages in the `man/` directory. These should be prefixed
with `telodendria-`. You may also wish to ship the `docs/` directory
so that the user can read the documentation offline, and ensure that
they are reading the correct documentation for the installed version.
- An init script. People that wish to install Telodendria on their
system using your package are going to expect it to be integrated
enough that Telodendria can easily be 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. **Note:** Telodendria *does not* fork itself to the background;
the init script should do that.
You may wish to optionally create a dedicated user under which
Telodendria should run. Telodendria can be directly started as that
user, or start as root and be configured to automatically drop to that
user. Additionally, it might be helpful to provide a default
configuration, which can be placed in the samples directory on your
platform, or in a default location that Telodendria will load from.
A good default directory that you may wish to provide for configuration,
data, and logs could perhaps be `/var/telodendria` on Unix-like systems.
Once you have collected the necessary files and directories that need
to be installed, make sure your package performs the following tasks
on install:
- If necessary and depending on the configuration used, create a new
system user for the Telodnedria daemon to run as.
- If conventional for your system, enable the Telodendria init script
so that Telodendria is started on system boot.
- Instruct the user to carefully read the [Setup](../user/setup.md)
(`docs/user/setup.md`) instructions and the
[Configuration](../user/config.md) (`docs/user/config.md`) instructions
before starting Telodendria.
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.
Remember to publicly document the setup of Telodendria on your platform
if there are additional steps required that are not mentioned in the
official Telodendria documentation. This ensures that users can get
up and running quickly and easily. If you're packaging Telodendria
for a container system such as Docker, you can omit the things that
containers typically do not have, such as the init scripts and
documentation.
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
developer's opinions of where things should go, and since the
configuration lives in the database, it is fairly self contained.
If there are any changes necessary to the upstream code or build
system that would make your job in porting Telodendria easier, do not
hesitate to get involved by opening an issue and/or submitting a pull
request.

View file

@ -1,119 +0,0 @@
.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

View file

@ -1,73 +0,0 @@
.Dd $Mdocdate: April 30 2023 $
.Dt TELODENDRIA 8
.Os Telodendria Project
.Sh NAME
.Nm telodendria
.Nd Daemon command line manual for Telodendria administrators.
.Sh SYNOPSIS
.Nm
.Op Fl nVv
.Op Fl f Ar file
.Sh DESCRIPTION
.Nm
is a Matrix homeserver written entirely from scratch in ANSI C.
It is designed to be lightweight and simple, yet functional.
.sp
The options are as follows:
.Bl -tag -width Ds
.It Fl d Ar dir
Specify the data directory to use. All persistant storage that
Telodendria requires is saved and loaded here.
.It Fl V
Only print the version information header and then quit.
.It Fl v
Verbose mode. This overrides the configuration file and sets the
log level to
.Em LOG_DEBUG .
It also enables extra logging of memory operations, which can
be useful for debugging.
.El
.Sh ENVIRONMENT
.Nm
does not read any environment variables. All configuration should
be done via the configuration file.
.Sh FILES
Just the data directory. Telodendria does not read any files outside
of its data directory, with the exception of TLS files if configured.
.Sh SIGNALS
Telodendria recognizes a number of signals that it handles:
.Bl -tag -width Ds
.It PIPE
This signal is ignored, because all I/O errors should be handled
properly.
.It USR1
Perform a soft restart by shutting down the HTTP servers and resetting
all program state. However, the daemon process does not exit.
.It TERM
Perform a clean shutdown after all existing connections are closed.
.It INT
Perform a clean shutdown after all existing connections are closed.
.El
.Pp
Any other signals are not explicitly handled, so they have the
default behavior defined by the operating system.
.Sh EXIT STATUS
.Nm
exits with a non-0 exit code if the configuration file is invalid, or
one or more required paths is inaccessible.
.Nm
will print an error to the log and then terminate abnormally.
.Pp
.Nm
exits with a code of 0 if the configuration file is valid, all
paths and files required are accessible, and the HTTP listener starts
as intended. If
.Nm
is sent a signal that it catches after it begins servicing requests, it
will still exit with a code of 0 after it safely shuts down, because
the bootstrap process completed successfully, and by all accounts,
it ran normally and exitted normally.
.Sh SEE ALSO
.Xr telodendria 7 ,
.Xr telodendria-setup 7 ,
.Xr telodendria-admin 7