diff --git a/docs/README.md b/docs/README.md index 94002ae..e927e8f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/user/install.md b/docs/user/install.md new file mode 100644 index 0000000..56a8f30 --- /dev/null +++ b/docs/user/install.md @@ -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. diff --git a/docs/user/usage.md b/docs/user/usage.md new file mode 100644 index 0000000..8fcd604 --- /dev/null +++ b/docs/user/usage.md @@ -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 `** 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.