WIP documentation.

Luka Vandervelden 2019-11-12 20:03:45 +01:00
parent 1a90b285d2
commit b074dae4e6
3 changed files with 212 additions and 0 deletions

doc/service.1.scd Normal file
View File

@ -0,0 +1,117 @@
service - system services control and querying interface
*service* add <service> [options]
*service* start <service>
*service* stop <service>
*service* status [-v] [service [service [...]]
*service* reload <service>
*service* del <service>
*service* show <service>
**service** is a tool that starts, stops, lists, queries, creates or removes system services.
**service** abstracts their configuration and handles their dependencies to one another.
Some general concepts about WeirdOS services management and boot procedure can be found in *service*(7).
## Identifying Services
service show <id>
service status [-v|--verbose] [id [id [...]]]
Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/').
*service show* shows all of a services relationship to other services as well as its full configuration as handled by `service`.
*service status* shows the status of one or multiple services, including whether they are currently running or not.
If no parameter is provided to the `status` command, it will show the status of all services.
If the `--verbose` flag is provided, informations about what tokens a service produces or consumes, as well as the ports it reserves, will be displayed as well.
## Starting Services
service start <id>
If a service that has dependencies is requested to be started, its dependencies will be started beforehand.
If a service is depended on by a non-runnable service, the non-runnable services will have their configuration and deployable files generated once its last dependency is started.
An example for this is a static website that depends on a web server: if the web server is started, the static websites files and possible configuration will be generated or installed where they will be served.
## Stopping Services
service stop <id>
## Adding Services
service add <id> [options]
The **service add** command can be used to create a service.
Only services that have been “added” to the list of known services can be started.
It takes as first parameter the *id* of the service to create.
The service type defaults to the name of the service to be created.
## Removing Services
service del <id> [options]
The **service del** command removes a service from the system.
Be careful, as this command also removes its configuration and data.
*service del* will not let you remove services that are being depended on unless you provide a `--force` flag.
*service del* will stop services before removing them.
## Starting a Service
$ service start gitea
## Registering a Single Service
service add postgresql
service start postgresql
## Registering Multiple Services with Dependencies
service add nginx
service add postgresql
service add gitea http=nginx postgresql=postgresql domain=gitea.test
In this example, the dependencies of the “gitea” service could have been guessed automatically.
The following example does the exact same thing but lets `service` guess dependencies.
service add nginx
service add postgresql
service add gitea domain=gitea.test
Luka Vandervelden <lukc@upyum.com>

doc/service.7.scd Normal file
View File

@ -0,0 +1,52 @@
service - services and applications management
The *service*(1) tool is used to manage services.
The *rc*(1) script is used to start the components of the system not handled by *init*(1).
*rc* is usually the first application to call *service*.
Service ids are the name of a service, that may be prefixed by the name of their environment and a slash ('/').
The default environment for services, if none is provided, is named *root*.
Interactions between services is represented by *tokens*.
Their names and behavior are arbitrary, and they only serve in establishing conventions between services.
## /etc/rc/services
Directory in which the metadata about instances of services handled by *service*(1) are stored.
## /etc/rc/environments
Directory in which the metadata about environments of services handled by *service*(1) are stored.
The *root* environment is virtual and does not have a matching entry.
## /usr/weirdos/share/services
Directory in which the behavior of services is stored.
## /usr/weirdos/share/templates
Directory in which configuration templates to be used by services *gen-config* are stored.
Luka Vandervelden <lukc@upyum.com>

View File

@ -45,6 +45,14 @@ for file in utils/*; do
for file in doc/*; do
[[ "$file" =~ .*\.scd$ ]] || continue
# FIXME: This should be upstreamed.
function script.install {
if [[ "false" = "${install[$target]}" ]]; then
@ -56,3 +64,38 @@ function script.install {
function scdoc.prelude {
for target in $targets; do
[[ "${type[$target]}" == "scdoc" ]] || continue
if [[ -z "${install[$target]}" ]]; then
local section="${file%.scd}"
function SCD {
SED "$@" | sed 's|SED|SCD|'
function scdoc.build {
write "${target}: ${sources[$target]}"
write "\t@echo '$(SCD $target)'"
write "\t${Q}scdoc < ${sources[$target]} > $target || rm $target"
function scdoc.install {
script.install "$@"
function scdoc.uninstall {
script.uninstall "$@"
function scdoc.clean {
script.clean "$@"