forked from Telodendria/Telodendria
Remove install/uninstall recipes, and replace telodendria-setup with package
man page.
This commit is contained in:
parent
8db83fe1fc
commit
71a6842302
4 changed files with 115 additions and 173 deletions
92
man/man7/package.7
Normal file
92
man/man7/package.7
Normal 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
|
||||
|
|
@ -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
|
||||
|
|
@ -60,14 +60,6 @@ and check the signature. To check the signature, you'll need
|
|||
<a href="/telodendria-signify.pub">
|
||||
telodendria-signify.pub</a>.
|
||||
</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>
|
||||
<tr>
|
||||
<th>Version</th>
|
||||
|
|
@ -106,6 +98,22 @@ information.
|
|||
<p>
|
||||
You can find the change log in the documentation.
|
||||
</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>
|
||||
<p>
|
||||
<b>Telodendria</b>'s documentation is distributed with the source
|
||||
|
|
@ -129,12 +137,6 @@ the source code license is.
|
|||
</td>
|
||||
</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>
|
||||
Command line usage for <b>Telodendria</b> administrators.
|
||||
|
|
@ -160,6 +162,13 @@ Contributing guide.
|
|||
<th>Description</th>
|
||||
</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>
|
||||
Build script and patch generation instructions.
|
||||
|
|
|
|||
25
tools/bin/td
25
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue