.\"
.\" Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd August 04, 2022
.Dt SCI 7
.Os
.\" NAME
.Sh NAME
.Nm sci
.Nd simple continuous integration framework
.\" DESCRIPTION
.Sh DESCRIPTION
The
.Nm
framework is a set of utilities to run automated tasks similarly to alternatives
such as jenkins or buildbot.
.Pp
In contrast to those,
.Nm sci
does not know how to build project nor how to retrieve information when to
build them. It only works by user project scripts to be executed upon addition
of jobs.
.Pp
It is designed in mind to be as simple as possible to improve flexibility and
simple documentation.
.\" OVERVIEW
.Sh OVERVIEW
The
.Nm
framework is split into three individual programs that are used independently.
The communication workflow is:
.Bd -literal
              o ---- scictl
             /
scid (HTTP) o
             \\
	      o ---- sciworkerd
.Ed
.Pp
The
.Nm scid
daemon is the unique access to the SQLite database and simply take requests
over an HTTP REST API to retrieve and set results into it.
.Pp
The
.Nm scictl
is the administrative utility to update the database using a command line
interface. It can also be used to create jobs and their result manually if
wanted.
.Pp
The
.Nm sciworkerd
is a daemon executing jobs on a host machine. It access the jobs listing by
querying
.Nm scid
and output their result.
.\" ENTITIES
.Sh ENTITIES
The process handle different kind of entities in the database.
.\" PROJECTS
.Ss PROJECTS
A project is an user description of what to be automated and tested. It has a
name, description, project URL and a script to execute. They can be created
using the
.Cm project-add
command from
.Nm scictl .
.\" JOBS
.Ss JOBS
Jobs are tasks to be performed by any worker for a given project. It has an user
arbitrary tag that will be passed to the project script as sole argument. In
contrats to many CI system, the sci framework has no information about how to
build and access a project and as such the job tag can be anything up to the
user (a SCM repo revision, date, simple id, etc).
.\" WORKERS
.Ss WORKERS
A worker is a host system that connects to
.Nm scid
using HTTP protocol to get acces to jobs to perform, execute them and finally
send the result back. They have been designed to use HTTP to allow remote usage.
.\" JOB RESULTS
.Ss JOB RESULTS
A job result is the detail about a job ran by a worker for a specific project.
If a job exists for one project and there are four workers on the user
installation, there will be four job results. It has an exit code (got from the
user script), a log console (capture from standard output and error) and a
timestamp when it was started.
.\" SEE ALSO
.Sh SEE ALSO
.Xr scictl 8 ,
.Xr scid 8 ,
.Xr sciworkerd 8