|
13
|
1 .\" |
|
|
2 .\" Copyright (c) 2021 David Demelier <markand@malikania.fr> |
|
|
3 .\" |
|
|
4 .\" Permission to use, copy, modify, and/or distribute this software for any |
|
|
5 .\" purpose with or without fee is hereby granted, provided that the above |
|
|
6 .\" copyright notice and this permission notice appear in all copies. |
|
|
7 .\" |
|
|
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES |
|
|
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF |
|
|
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR |
|
|
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
|
|
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN |
|
|
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF |
|
|
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. |
|
|
15 .\" |
|
|
16 .Dd June 30, 2021 |
|
|
17 .Dt SCI 7 |
|
|
18 .Os |
|
|
19 .\" NAME |
|
|
20 .Sh NAME |
|
|
21 .Nm sci |
|
|
22 .Nd simple continuous integration framework |
|
|
23 .\" DESCRIPTION |
|
|
24 .Sh DESCRIPTION |
|
|
25 The |
|
|
26 .Nm |
|
|
27 framework is a set of utilities to run automated tasks similarly to alternatives |
|
|
28 such as jenkins or buildbot. |
|
|
29 .Pp |
|
|
30 In contrast to those, |
|
|
31 .Nm sci |
|
|
32 does not know how to build project nor how to retrieve information when to build |
|
|
33 them. It only works by user user project script to be executed upon addition of |
|
|
34 jobs. |
|
|
35 .Pp |
|
|
36 It is designed in mind to be as simple as possible to improve flexibility and |
|
|
37 simple documentation. |
|
|
38 .\" OVERVIEW |
|
|
39 .Sh OVERVIEW |
|
|
40 The |
|
|
41 .Nm |
|
|
42 framework is split into four individual programs that are used independently. |
|
|
43 The communication workflow is: |
|
|
44 .Bd -literal |
|
|
45 scid <-- (UNIX socket) --> scictl |
|
|
46 ^-- (UNIX socket) --> sciwebd <-- (HTTP with JSON) --> sciworkerd |
|
|
47 .Ed |
|
|
48 .Pp |
|
|
49 The |
|
|
50 .Nm scid |
|
|
51 daemon is the unique access to the SQLite database and simply take requests over |
|
|
52 a UNIX socket to retrieve and set results into it. |
|
|
53 .Pp |
|
|
54 The |
|
|
55 .Nm scictl |
|
|
56 is the administrative utility to update the database using a command line |
|
|
57 interface. It can also be used to create jobs and their result manually if |
|
|
58 wanted. |
|
|
59 .Pp |
|
|
60 The |
|
|
61 .Nm sciwebd |
|
|
62 is a CGI/FastCGI utility daemon that parse HTTP requests and dispatch them to |
|
|
63 .Nm scid |
|
|
64 using a JSON API. As it is written using CGI it does not involve SSL nor |
|
|
65 authentication and must be done using a HTTP web server proxy if needed. |
|
|
66 .Pp |
|
|
67 The |
|
|
68 .Nm sciworkerd |
|
|
69 is a daemon executing jobs on a host machine. It access the jobs listing by |
|
|
70 querying |
|
|
71 .Nm sciwebd |
|
|
72 and output their result. By this way, it can run on remotes machine while both |
|
|
73 .Nm scid |
|
|
74 and |
|
|
75 .Nm sciwebd |
|
|
76 can run on a different machine. |
|
|
77 .\" ENTITIES |
|
|
78 .Sh ENTITIES |
|
|
79 The process handle different kind of entities in the database. |
|
|
80 .\" PROJECTS |
|
|
81 .Ss PROJECTS |
|
|
82 A project is an user description of what to be automated and tested. It has a |
|
|
83 name, description, project URL and a script to execute. They can be created |
|
|
84 using the |
|
|
85 .Cm project-add |
|
|
86 command from |
|
|
87 .Nm scictl . |
|
|
88 .\" JOBS |
|
|
89 .Ss JOBS |
|
|
90 Jobs are tasks to be performed by any worker for a given project. It has an user |
|
|
91 arbitrary tag that will be passed to the project script as sole argument. In |
|
|
92 contrats to many CI system, the sci framework has no information about how to |
|
|
93 build and access a project and as such the job tag can be anything up to the |
|
|
94 user (a SCM repo revision, date, simple id, etc). |
|
|
95 .\" WORKERS |
|
|
96 .Ss WORKERS |
|
|
97 A worker is a host system that connects to |
|
|
98 .Nm sciwebd |
|
|
99 using HTTP protocol to get acces to jobs to perform, execute them and finally |
|
|
100 send the result back. They have been designed to use HTTP to allow remote usage. |
|
|
101 .\" JOB RESULTS |
|
|
102 .Ss JOB RESULTS |
|
|
103 A job result is the detail about a job ran by a worker for a specific project. |
|
|
104 If a job exists for one project and there are four workers on the user |
|
|
105 installation, there will be four job results. It has an exit code (got from the |
|
|
106 user script), a log console (capture from standard output and error) and a |
|
|
107 timestamp when it was started. |
|
|
108 .\" SEE ALSO |
|
|
109 .Sh SEE ALSO |
|
|
110 .Xr scid 8 , |
|
|
111 .Xr scictl 8 , |
|
|
112 .Xr sciwebd 8 , |
|
|
113 .Xr sciworkerd 8 |
