From 71a68423027b1d9595b7c6c06513c67cff088bd2 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sun, 20 Nov 2022 00:12:53 +0000 Subject: [PATCH] Remove install/uninstall recipes, and replace telodendria-setup with package man page. --- man/man7/package.7 | 92 ++++++++++++++++++++++++ man/man7/telodendria-setup.7 | 134 ----------------------------------- site/index.html | 37 ++++++---- tools/bin/td | 25 ------- 4 files changed, 115 insertions(+), 173 deletions(-) create mode 100644 man/man7/package.7 delete mode 100644 man/man7/telodendria-setup.7 diff --git a/man/man7/package.7 b/man/man7/package.7 new file mode 100644 index 0000000..3b5a064 --- /dev/null +++ b/man/man7/package.7 @@ -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 diff --git a/man/man7/telodendria-setup.7 b/man/man7/telodendria-setup.7 deleted file mode 100644 index da9484c..0000000 --- a/man/man7/telodendria-setup.7 +++ /dev/null @@ -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 diff --git a/site/index.html b/site/index.html index 02c7eab..66d198b 100644 --- a/site/index.html +++ b/site/index.html @@ -60,14 +60,6 @@ and check the signature. To check the signature, you'll need telodendria-signify.pub.

-

-If your operating system has an official package or port of -Telodendria, 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. -

@@ -106,6 +98,22 @@ information.

You can find the change log in the documentation.

+

+If your operating system has an official package or port of +Telodendria, 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. +

+

+If your operating system does not have a package or port of +Telodendria, please consult the +package(7) page for guidelines +related to packaging Telodendria for your system. +

Documentation

Telodendria's documentation is distributed with the source @@ -129,12 +137,6 @@ the source code license is.

- - - - + + + +
Version
telodendria-setup(7) -Setup instructions for OpenBSD. -
telodendria(8) Command line usage for Telodendria administrators. @@ -160,6 +162,13 @@ Contributing guide. Description
package(7) +Want to package Telodendria for your operating system, or just install it to +your system from source? Look no further than this page. +
td(8) Build script and patch generation instructions. diff --git a/tools/bin/td b/tools/bin/td index 77ed797..3b62631 100644 --- a/tools/bin/td +++ b/tools/bin/td @@ -93,31 +93,6 @@ recipe_build() { 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() { if [ -f "build/$PROG" ]; then "build/$PROG" -f contrib/development.conf