forked from Telodendria/Telodendria
Add usage and install documentation.
This commit is contained in:
parent
ee62d31c68
commit
93e6582db5
3 changed files with 117 additions and 1 deletions
|
@ -8,7 +8,7 @@ issue, and, even better, a pull request to fix the issue.
|
||||||
|
|
||||||
- [System Requirements](user/requirements.md)
|
- [System Requirements](user/requirements.md)
|
||||||
- [Install](user/install.md)
|
- [Install](user/install.md)
|
||||||
- [Command Line Options](user/cmd.md)
|
- [Usage & Running](user/usage.md)
|
||||||
- [Set Up](user/setup.md)
|
- [Set Up](user/setup.md)
|
||||||
- [Configuration Options](user/config.md)
|
- [Configuration Options](user/config.md)
|
||||||
- [Administrator API](user/admin.md)
|
- [Administrator API](user/admin.md)
|
||||||
|
@ -20,6 +20,7 @@ issue, and, even better, a pull request to fix the issue.
|
||||||
|
|
||||||
## Miscellaneous
|
## Miscellaneous
|
||||||
|
|
||||||
|
- [Matrix Specification](https://spec.matrix.org) ([Mirror](https://telodendria.io/spec.matrix.org))
|
||||||
- [Change Log](CHANGELOG.md)
|
- [Change Log](CHANGELOG.md)
|
||||||
- [Project Road Map](ROADMAP.md)
|
- [Project Road Map](ROADMAP.md)
|
||||||
|
|
||||||
|
|
51
docs/user/install.md
Normal file
51
docs/user/install.md
Normal 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
64
docs/user/usage.md
Normal 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.
|
Loading…
Reference in a new issue