latticeware/Telodendria
1
0
Fork 0
forked from Telodendria/Telodendria
Code Pull requests Activity

Remove install/uninstall recipes, and replace telodendria-setup with package

Browse source 
man page.
This commit is contained in:
Jordan Bancino 2022-11-20 00:12:53 +00:00
parent 8db83fe1fc
commit 71a6842302
4 changed files with 115 additions and 173 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
man/man7/package.7 Normal file
View file

@ -0,0 +1,92 @@
.Dd $Mdocdate: November 20 2022 $
.Dt PACKAGE 7
.Os Telodendria Project
.Sh NAME
.Nm package
.Nd Some guidelines for packaging Telodendria for your 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 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, or just install it from source, though that's not recommended.
.Pp
See
.Xr td 8
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. An init script suitable for your platform might be
available in
.Pa contrib/ ,
but if not, it should be trivial to write your own. If you do end up making
an official package for your system, feel free to submit your init script
to be added to the
.Pa contrib/
directory.
.It
A sample
.Pa telodendria.conf
file. Whether this file is placed at the actual configuration file location,
or a directory containing configuration file samples is entirely up to the
packager. 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 sample
.Pa telodendria.conf
as well as the
.Xr telodendria.conf 5
manual page before starting Telodendria.
.El
.Pp
The goal of a package should be to get everything as ready-to-run as possible.
The user should only have to change one or two default options in the configuration
file before Telodendria can be started.
.Pp
Remember to publicly document the setup of Telodendria on your platform so
that users can easily get Telodendria 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.
.Sh SEE ALSO
.Xr telodendria-contributing 7 ,
.Xr td 8 ,
.Xr telodendria 7

134
man/man7/telodendria-setup.7
View file

@ -1,134 +0,0 @@
.Dd $Mdocdate: November 6 2022 $
.Dt TELODENDRIA-SETUP 7
.Os Telodendria Project
.Sh NAME
.Nm telodendria-setup
.Nd Guide to getting Telodendria running on your system.
.Sh DESCRIPTION
This page aims to provide a high-level overview of how to
get Telodendria running on your system from source. It assumes
that you're running OpenBSD, or know how to translate OpenBSD
commands into your system's commands, and that you are using an
an official distribution tarball. If you are using your system's
package manager to install Telodendria, you should refer to the
package maintainer's installation instructions instead of these
instructions.
.Pp
If you're a package maintainer, or would like to be, these
instructions might also be helpful for you as well; you can
use them to learn how the process is designed to work, so you
can mimic it on your system.
.Sh PREREQUISITES
To build Telodendria, you just need a POSIX system and C compiler.
If your system does not ship with a C compiler, please install
one before continuing with these directions.
.Pp
The build script relies on a POSIX shell implementation, as well
as the standard userspace utilities specified by POSIX.
.Pp
This should be obvious, but you'll also need a way to
download files to your machine, or otherwise copy them into place.
You'll also need
.Xr tar 1 ,
and
.Xr gzip 1
to extract the downloaded tarball.
.Sh GETTING THE CODE
You can download the source code for Telodendria by going to
the official website and downloading a tarball from the table.
Otherwise, you can download the tarball and supplemental files
directly:
.Bd -literal -offset indent
$ export VERSION=x.x.x # Set version of Telodendria you want
$ ftp https://telodendria.io/pub/v$VERSION/Telodendria-v$VERSION.tar.gz
$ ftp https://telodendria.io/pub/v$VERSION/Telodendria-v$VERSION.tar.gz.{sha256,sig}
.Ed
.Pp
Before you extract the tarball, it is a good idea to verify both its checksum
and its signature. Use
.Xr sha256 1
to verify that the download was not corrupted in transit:
.Bd -literal -offset indent
$ sha256 -C Telodendria-v$VERSION.tar.gz.sha256 Telodendria-v$VERSION.tar.gz
.Ed
.Pp
Use
.Xr signify 1
to verify that the download was legitimately published by the Telodendria
project:
.Bd -literal -offset indent
$ signify -V -p telodendria-signify.pub -m Telodendria-v$VERSION.tar.gz
.Ed
.Pp
You can obtain
.Pa telodendria-signify.pub
from the official website. While you may absolutely obtain the tarball
and checksum files from mirrors or other sources, do not obtain the public
key file from any other sources than the official website. Downloads from
other sources should be verified by the official public key only:
.Bd -literal -offset indent
$ ftp https://telodendria.io/telodendria-signify.pub
.Ed
.Pp
Finally, only when the tarball is verified, you can extract it:
.Bd -literal -offset indent
$ tar -xzf Telodendria-v$VERSION.tar.gz
$ cd Telodendria-v$VERSION
.Ed
.Sh BUILDING AND INSTALLING
In the source directory, just run the following commands:
.Bd -literal -offset indent
$ . tools/env.sh
$ td build
$ doas td install
.Ed
.Pp
This will compile the code, and install the output binary, along
with all of the documentation and configuration files, to the system.
.Pp
.Sy Packagers:
It might be beneficial to take a look at the install recipe in the
.Xr td 8
script so you know what files go where. Adapt the general procedure
for your operating system.
.Sh CONFIGURATION
A sufficiently complete configuration file should have been installed
to
.Pa /etc/telodendria.conf .
Open it with your preferred editor, and go through each line, making
sure everything is set appropriately for your setup. Consult the
.Xr telodendria.conf 5
and
.Xr Config 5
pages for a comprehensive list of all the available options and a
description for each option, as well as the general syntax of the
configuration file. You'll most certainly have to set your
server's name and base URL. Optionally, specify an identity server,
and whether or not you want to enable federation and registration.
All other options should have sane defaults for most systems.
.Sh STARTING TELODENDRIA
Once you've written the configuration file, it should just be as
easy as starting the
.Dv telodendria
daemon:
.Bd -literal -offset indent
$ rcctl enable telodendria
$ rcctl start telodendria
.Ed
.Pp
It might be a good idea to check the log file to make sure everything
started okay and is running fine.
.Pp
At this point, it would be a very good idea to configure a reverse
proxy. The
.Pa contrib/
directory of the source code has an example
.Xr relayd.conf 5
file which can be installed as-is into the typical location, or
integrated into an existing configuration. At some point in the
future, a reverse proxy may not be required for TLS, but it will
always be recommended because it provides more control and security.
.Sh SEE ALSO
.Xr td 8 ,
.Xr telodendria.conf 5 ,
.Xr telodendria 8

37
site/index.html
View file

@ -60,14 +60,6 @@ and check the signature. To check the signature, you'll need
<a href="/telodendria-signify.pub"> <a href="/telodendria-signify.pub">
telodendria-signify.pub</a>. telodendria-signify.pub</a>.
</p> </p>
<p>
If your operating system has an official package or port of
<b>Telodendria</b>, you should prefer to use that instead of manually
downloading the source and building it. If your operating system's
package or port is too out of date for your tastes, please contact
the package's maintainers to notify them, or offer to update the
package yourself.
</p>
<table> <table>
<tr> <tr>
<th>Version</th> <th>Version</th>
@ -106,6 +98,22 @@ information.
<p> <p>
You can find the change log in the documentation. You can find the change log in the documentation.
</p> </p>
<p>
If your operating system has an official package or port of
<b>Telodendria</b>, you should prefer to use that instead of manually
downloading the source and building it. Consult your operating system's
manual for how to install packages, as well as the official repository,
to see if a package is available. If your operating system's
package or port is too out of date for your tastes, please contact
the package's maintainers to notify them, or offer to update the
package yourself.
</p>
<p>
If your operating system does <i>not</i> have a package or port of
<b>Telodendria</b>, please consult the
<a href="/man/man7/package.7.html">package(7)</a> page for guidelines
related to packaging <b>Telodendria</b> for your system.
</p>
<h2 id="documentation">Documentation</h2> <h2 id="documentation">Documentation</h2>
<p> <p>
<b>Telodendria</b>'s documentation is distributed with the source <b>Telodendria</b>'s documentation is distributed with the source
@ -129,12 +137,6 @@ the source code license is.
</td> </td>
</tr> </tr>
<tr> <tr>
<td><a href="man/man7/telodendria-setup.7.html">telodendria-setup(7)</a></td>
<td>
Setup instructions for OpenBSD.
</td>
</tr>
<tr>
<td><a href="man/man8/telodendria.8.html">telodendria(8)</a></td> <td><a href="man/man8/telodendria.8.html">telodendria(8)</a></td>
<td> <td>
Command line usage for <b>Telodendria</b> administrators. Command line usage for <b>Telodendria</b> administrators.
@ -160,6 +162,13 @@ Contributing guide.
<th>Description</th> <th>Description</th>
</tr> </tr>
<tr> <tr>
<td><a href="man/man7/package.7.html">package(7)</a></td>
<td>
Want to package Telodendria for your operating system, or just install it to
your system from source? Look no further than this page.
</td>
</tr>
<tr>
<td><a href="man/man8/td.8.html">td(8)</a></td> <td><a href="man/man8/td.8.html">td(8)</a></td>
<td> <td>
Build script and patch generation instructions. Build script and patch generation instructions.

25
tools/bin/td
View file

@ -93,31 +93,6 @@ recipe_build() {
fi fi
} }
recipe_install() {
cp -v "build/$PROG" "$PREFIX/bin/$PROG"
cp -v "contrib/production.conf" "/etc/telodendria.conf"
cp -v "contrib/telodendria.rc" "/etc/rc.d/telodendria"
mkdir "/var/telodendria"
useradd _telodendria
chown "_telodendria:_telodendria" "/var/telodendria"
find man -name 'telodendria*\.[1-8]' -exec cp -v {} "$PREFIX/{}" \;
}
recipe_uninstall() {
rm -v "$PREFIX/bin/$PROG"
rm -v "/etc/rc.d/telodendria"
userdel "_telodendria"
groupdel "_telodendria"
find "$PREFIX/man" -name 'telodendria*\.[1-8]' -delete
echo "Not removing configuration file at /etc/telodendria.conf"
echo "Not removing data directory at /var/telodendria"
}
recipe_run() { recipe_run() {
if [ -f "build/$PROG" ]; then if [ -f "build/$PROG" ]; then
"build/$PROG" -f contrib/development.conf "build/$PROG" -f contrib/development.conf