forked from lda/telodendria
Add porting instructions.
This commit is contained in:
parent
93e6582db5
commit
3cb04417ff
3 changed files with 94 additions and 192 deletions
94
docs/dev/ports.md
Normal file
94
docs/dev/ports.md
Normal 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.
|
||||||
|
|
||||||
|
|
@ -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
|
|
||||||
|
|
@ -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
|
|
||||||
Loading…
Reference in a new issue