--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/sci.7.in	Wed Jun 30 11:33:54 2021 +0200
@@ -0,0 +1,113 @@
+.\"
+.\" Copyright (c) 2021 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 June 30, 2021
+.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 user project script 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 four individual programs that are used independently.
+The communication workflow is:
+.Bd -literal
+scid <-- (UNIX socket) --> scictl
+     ^-- (UNIX socket) --> sciwebd <-- (HTTP with JSON) --> sciworkerd
+.Ed
+.Pp
+The
+.Nm scid
+daemon is the unique access to the SQLite database and simply take requests over
+a UNIX socket 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 sciwebd
+is a CGI/FastCGI utility daemon that parse HTTP requests and dispatch them to
+.Nm scid
+using a JSON API. As it is written using CGI it does not involve SSL nor
+authentication and must be done using a HTTP web server proxy if needed.
+.Pp
+The
+.Nm sciworkerd
+is a daemon executing jobs on a host machine. It access the jobs listing by
+querying
+.Nm sciwebd
+and output their result. By this way, it can run on remotes machine while both
+.Nm scid
+and
+.Nm sciwebd
+can run on a different machine.
+.\" 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 sciwebd
+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 scid 8 ,
+.Xr scictl 8 ,
+.Xr sciwebd 8 ,
+.Xr sciworkerd 8