Add usage and install documentation.

This commit is contained in:
Jordan Bancino 2023-09-07 21:10:46 -04:00
parent ee62d31c68
commit 93e6582db5
3 changed files with 117 additions and 1 deletions

View file

@ -8,7 +8,7 @@ issue, and, even better, a pull request to fix the issue.
- [System Requirements](user/requirements.md)
- [Install](user/install.md)
- [Command Line Options](user/cmd.md)
- [Usage & Running](user/usage.md)
- [Set Up](user/setup.md)
- [Configuration Options](user/config.md)
- [Administrator API](user/admin.md)
@ -20,6 +20,7 @@ issue, and, even better, a pull request to fix the issue.
## Miscellaneous
- [Matrix Specification](https://spec.matrix.org) ([Mirror](https://telodendria.io/spec.matrix.org))
- [Change Log](CHANGELOG.md)
- [Project Road Map](ROADMAP.md)

51
docs/user/install.md Normal file
View file

@ -0,0 +1,51 @@
# Installation
There are multiple methods of installing Telodendria. Choose the one
best suited to your use case.
## Package Manager Or System Ports
This is the recommended way to install Telodendria. If your operating
system has an official package or port of Telodendria, you should
prefer to use that instead of the other methods documented here,
because your operating system or software distribution will have
already figured out how to best integrate Telodendria with your system.
Consult your operating system or software distribution's system
manual for instructions on how to install packages. Also consult the
official repository of your distribution to see if a package is
available. If a package exists but it is too out of date for your
tastes, please contact the package's maintainer to notify them, or
offer to update the package yourself using the
[porting instructions](../dev/ports.md).
If you are maintaining a port or package for an operating system or
software distribution, open a pull request to include your
platform-specific instructions as a subheader of this section.
Eventually, this section should contain basic instructions for the
operating systems that have packages or ports.
See [Ports](../dev/ports.md) for the project's distribution
philosophy.
## Container
At this time, Telodendria does not have any officially recommended
procedure for running in a container such as Docker or Vagrant. You
may find helpful files in the [`contrib/`](../../contrib) directory,
however.
If you are publishing container images, please open a pull request to
add your source files to `contrib/`, as well as to add documentation
under this section explaining how to get set started.
## Release Binary
At this time, Telodendria does not publish any official binaries that
can be downloaded. The tentative plan is to eventually provide binaries
with each release for a number of supported platforms. When that
happens, instructions will be provided here for dealing with the
binaries.
## From Source
**TODO:** Update this section before #19 is closed.

64
docs/user/usage.md Normal file
View file

@ -0,0 +1,64 @@
# Usage
This document provides general documentation on how to use the
`telodendria` server binary, as well as details on how it behaves.
The details here will be useful for setting up init systems, running
Telodendria in a container, or manually executing the binary for
testing or debugging purposes.
## Command Line Options
Typically, Telodendria is controlled via the
[Administrator API](admin.md), but the Telodendria binary does include
a few command line options, which can be used in init scripts or for
debugging purposes.
The command line arguments are as follows:
- **`-d <dir>`** Specify the data directory to use. All persistent
storage that Telodendria requires is saved to and loaded from here.
- **`-V`** Only print the version information header and then quit
with a success exit code.
- **`-v`** Verbose mode. This overrides the configuration and sets the
log level to `debug`. It also enables additional logging of memory
operations, which can be useful for debugging.
Before proposing additional command line arguments, consider whether or
not the functionality requested can be provided via a (potentially new
and as of yet uncreated) administrator API endpoint.
## Environment
Telodendria does not read any environment variables. All configuration
should be done via the [Configuration API](config.md).
## Signals
Telodendria recognizes and responds to a number of signals:
- **`PIPE`:** This signal is ignored, because all I/O errors should
already be handled properly.
- **`USR1`:** Perform a soft restart by shutting down the HTTP servers
and resetting the program state. Note that the daemon process does
not exit.
- **`TERM`:** Perform a clean shutdown after all existing connections
are closed.
- **`INT`:** Same as `TERM`.
Any other signals are not explicitly handled, so they have the
default behavior as defind by the operating system.
## Exit Status
Telodendria exits with a non-0 exit code if the configuration file is
invalid, or one or more of required paths or files is inaccessible.
Telodendria will print an error to the log and then terminate
abnormally.
Telodendria 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 Telodendria is sent a signal that it catches
after it begins servicing requests, it will still exit normally after
it safely shuts down, because the bootstrap process completed
successfully, and by all accounts, it ran normally and exitted
normally.