From 3cb04417ffd3cd93b6aad3a98c76072933b40d44 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Thu, 7 Sep 2023 21:53:22 -0400 Subject: [PATCH] Add porting instructions. --- docs/dev/ports.md | 94 ++++++++++++++++++++++++++++++++ man/man7/porting.7 | 119 ----------------------------------------- man/man8/telodendria.8 | 73 ------------------------- 3 files changed, 94 insertions(+), 192 deletions(-) create mode 100644 docs/dev/ports.md delete mode 100644 man/man7/porting.7 delete mode 100644 man/man8/telodendria.8 diff --git a/docs/dev/ports.md b/docs/dev/ports.md new file mode 100644 index 0000000..5154106 --- /dev/null +++ b/docs/dev/ports.md @@ -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. + diff --git a/man/man7/porting.7 b/man/man7/porting.7 deleted file mode 100644 index 2f24195..0000000 --- a/man/man7/porting.7 +++ /dev/null @@ -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 diff --git a/man/man8/telodendria.8 b/man/man8/telodendria.8 deleted file mode 100644 index 303703f..0000000 --- a/man/man8/telodendria.8 +++ /dev/null @@ -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