Telodendria/man/man7/telodendria-setup.7

75 lines
3 KiB
Groff

.Dd $Mdocdate: April 20 2023 $
.Dt TELODENDRIA-SETUP 7
.Os Telodendria Project
.Sh NAME
.Nm telodendria-setup
.Nd First-time setup instructions for Telodendria.
.Sh DESCRIPTION
.Pp
While Telodendria strives to be extremely simple to deploy, in most
circumstances a few basic setup steps will be necessary. Telodendria
does not have a traditional configuration file like most daemons.
Instead, its configuration lives in its database; as such, all
configuration happens through the administrator API. This design
decision makes Telodendria extremely flexible, because it is possible
to re-configure Telodendria without having to manually edit files
on the filesystem. It is also why the setup instructions provided
here are in the order they are. Please follow them carefully for the
best results.
.Pp
This page assumes that you have installed Telodendria in the way
prescribed by your operating system. Immediately following installation,
perform these steps, in this order:
.Bl -enum -width Ds
.It
Start Telodendria. Consult your operating system's documentation. If
you are running Telodendria directly from the source code directory,
use
.Xr td 8 .
.It
Assuming Telodendria started properly, it will spin up and initialize
its database directory with a simple\(emand importantly,
safe\(emdefault configuration, and a randomly-generated, single-use
registration token that grants a user all privileges documented in
.Xr telodendria-admin 7.
Consult the log file for this administrator registration token. The
log file is located in the data directory, and is named
.Pa telodendria.log .
.It
Use the registration token to register the administrator account. You
can do this using the client of your choice, or using tools such as
.Xr curl 1
or
.Xr http 1 .
The administrator account functions just like a normal local account,
except that it has all privileges granted to it, so it can make full
use of the administrator API.
.It
Using the access token for the administrator account, authenticate
with the administrator API and configure Telodendria as described
in
.Xr telodendria-config 7.
See
.Xr telodendria-admin 7
for the configuration endpoint details.
.El
.Pp
This is the recommended way to set up Telodendria. However, if you
wish to bypass the account creation step, and want to configure
Telodendria by directly writing a configuration file instead of using
the administrator API, you can manually create the configuration file
in the database before starting Telodendria. Simply create
.Pa config.json
following the description in
.Xr telodendria-config 7 ,
then start Telodnedria.
.Pp
While this alternative method may seem simpler and more convenient to
some administrators, it is only so in the short-term. Note that this
method is not supported, because it gives no access to the
administrator API whatsoever, unless you manually modify the database
to give a user admin privileges, which is error-prone and bypasses
some of Telodendria's safety mechanisms.
.Sh SEE ALSO
.Xr telodendria-admin 7 ,
.Xr telodendria-config 7