forked from lda/telodendria
Add porting instructions.
This commit is contained in:
parent
c2294723e6
commit
cb6963299c
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