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)
|
||||
- [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
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