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.
+

man/man7/porting.7

@@ -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

man/man8/telodendria.8

@@ -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