Mercurial > sci
changeset 35:084dee2bef50
man: updates
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 04 Aug 2022 18:01:29 +0200 |
parents | e52c762d8ba8 |
children | b84cea83b129 |
files | Makefile man/sci.7 man/sci.7.in man/scictl.8 man/scictl.8.in man/scid.8 man/scid.8.in man/sciwebd.8.in man/sciworkerd.8 man/sciworkerd.8.in |
diffstat | 10 files changed, 410 insertions(+), 581 deletions(-) [+] |
line wrap: on
line diff
--- a/Makefile Thu Aug 04 17:47:19 2022 +0200 +++ b/Makefile Thu Aug 04 18:01:29 2022 +0200 @@ -80,9 +80,8 @@ SCIWORKERD_OBJS= ${SCIWORKERD_SRCS:.c=.o} SCIWORKERD_DEPS= ${SCIWORKERD_SRCS:.c=.d} -MAN7= man/sci.7 -MAN8= man/scid.8 \ - man/sciworkerd.8 +MAN7= sci.7 +MAN8= scid.8 sciworkerd.8 TESTS= tests/test-db.c TESTS_OBJS= ${TESTS:.c=} @@ -176,9 +175,13 @@ mkdir -p ${DESTDIR}${BINDIR} cp scid/scid sciworkerd/sciworkerd ${DESTDIR}${BINDIR} mkdir -p ${DESTDIR}${MANDIR}/man7 - cp ${MAN7} ${DESTDIR}${MANDIR}/man7 + for m in ${MAN7}; do \ + sed ${SUBST} < man/$$m > ${DESTDIR}${MANDIR}/man7/$$m; \ + done mkdir -p ${DESTDIR}${MANDIR}/man8 - cp ${MAN8} ${DESTDIR}${MANDIR}/man8 + for m in ${MAN8}; do \ + sed ${SUBST} < man/$$m > ${DESTDIR}${MANDIR}/man8/$$m; \ + done clean: rm -f bcc tags cscope.out ${MAN7} ${MAN8} ${SQL_OBJS}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/sci.7 Thu Aug 04 18:01:29 2022 +0200 @@ -0,0 +1,104 @@ +.\" +.\" 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
--- a/man/sci.7.in Thu Aug 04 17:47:19 2022 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,113 +0,0 @@ -.\" -.\" 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 June 30, 2021-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 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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/scictl.8 Thu Aug 04 18:01:29 2022 +0200 @@ -0,0 +1,151 @@ +.\" +.\" 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 June 30, 2021-2022 +.Dt SCICTL 8 +.Os +.\" NAME +.Sh NAME +.Nm scictl +.Nd command line client to scid +.\" SYNOPSIS +.Sh SYNOPSIS +.\" job-add +.Nm +.Cm job-add +.Ar project +.Ar tag +.\" job-todo +.Nm +.Cm job-todo +.Ar worker +.\" project-add +.Nm +.Cm project-add +.Ar name +.Ar desc +.Ar url +.Ar script +.\" project-info +.Nm +.Cm project-info +.Ar name +.\" project-list +.Nm +.Cm project-list +.\" project-update +.Nm +.Cm project-update +.Ar name +.Ar key +.Ar value +.\" worker-add +.Nm +.Cm worker-add +.Ar name +.Ar desc +.\" worker-list +.Nm +.Cm worker-list +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +utility is a command line client that connects to +.Xr scid 8 +daemon. It is best used in conjunction with automated programs (such as cron) +and SCM integration to add new jobs to execute. It is also used as +administrative utility to create projects and workers. +.Pp +It is part of the +.Xr sci 7 +continuous integration framework. +.\" COMMANDS +.Sh COMMANDS +All commands are designed to return a human readable format but is guaranteed to +stay compatible across new versions. It can be used in scripts as well. +.Bl -tag -width project-update +.\" job-add +.It Cm job-add +Create a new job for the given +.Ar project +using the user arbitrary +.Ar tag +identifier. +.\" job-todo +.It Cm job-todo +List jobs that must be performed by the given +.Ar worker . +Jobs that were created earlier than the worker will not be listed to avoid +evaluating a possible high number of jobs. +.\" project-add +.It Cm project-add +Create a new project with +.Ar name , +an user description set with +.Ar desc , +a website arbitrary +.Ar url , +and a script code to execute specified by file +.Ar script . +If the +.Ar script +argument is set to +.Dq - +the standard input is read instead. +.\" project-info +.It Cm project-info +Get the detailed information, including the script code from +.Ar project . +.\" project-list +.It Cm project-list +List all projects, excluding the script code. +.\" project-update +.It Cm project-update +Update an existing +.Ar project +by setting its new fields. The +.Ar key +argument should be one of the argument specified in the +.Cm project-add +command. For example, to update the description of a project one should +specify +.Dq desc +as +.Ar name +argument and a new description as +.Ar key . +.Pp +Example: +.Bd -literal -offset indent +scictl project-update example desc "New description" +.Ed +.\" worker-add +.It Cm worker-add +Create a new worker with +.Ar name +user identifier and an arbirary +.Ar desc +description. +.\" worker-list +.It Cm worker-list +List all workers present on the system. It does not indicate if those workers +are actually running. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr sci 7 , +.Xr scid 8 , +.Xr sciworkerd 8
--- a/man/scictl.8.in Thu Aug 04 17:47:19 2022 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,182 +0,0 @@ -.\" -.\" 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 June 30, 2021-2022 -.Dt SCICTL 8 -.Os -.\" NAME -.Sh NAME -.Nm scictl -.Nd command line client to scid -.\" SYNOPSIS -.Sh SYNOPSIS -.\" job-add -.Nm -.Cm job-add -.Ar project -.Ar tag -.\" job-todo -.Nm -.Cm job-todo -.Ar worker -.\" jobresult-add -.Nm -.Cm jobresult-add -.Ar jobid -.Ar worker -.Ar exitcode -.Ar console -.\" project-add -.Nm -.Cm project-add -.Ar name -.Ar desc -.Ar url -.Ar script -.\" project-info -.Nm -.Cm project-info -.Ar name -.\" project-list -.Nm -.Cm project-list -.\" project-update -.Nm -.Cm project-update -.Ar name -.Ar key -.Ar value -.\" worker-add -.Nm -.Cm worker-add -.Ar name -.Ar desc -.\" worker-list -.Nm -.Cm worker-list -.\" DESCRIPTION -.Sh DESCRIPTION -The -.Nm -utility is a command line client that connects to -.Xr scid 8 -daemon. It is best used in conjunction with automated programs (such as cron) -and SCM integration to add new jobs to execute. It is also used as -administrative utility to create projects and workers. -.Pp -It is part of the -.Xr sci 7 -continuous integration framework. -.Pp -The following options are available -.Em before -the command name: -.Bl -tag -.It Fl s Ar path -Connect to the UNIX local socket specified by -.Ar path . -.El -.\" COMMANDS -.Sh COMMANDS -All commands are designed to return a human readable format but is guaranteed to -stay compatible across new versions. It can be used in scripts as well. -.Bl -tag -width project-update -.\" job-add -.It Cm job-add -Create a new job for the given -.Ar project -using the user arbitrary -.Ar tag -identifier. -.\" job-todo -.It Cm job-todo -List jobs that must be performed by the given -.Ar worker . -Jobs that were created earlier than the worker will not be listed to avoid -evaluating a possible high number of jobs. -.\" jobresult-add -.It Cm jobresult-add -Add a job result manually for the job id specified by -.Ar jobid -that was executed by the given -.Ar worker -The -.Ar exitcode -argument should be the project script exit status. The -.Ar console -argument should point to a file with the script's standard output and error. If -specified to -.Dq - -the standard input is read instead. -.\" project-add -.It Cm project-add -Create a new project with -.Ar name , -an user description set with -.Ar desc , -a website arbitrary -.Ar url , -and a script code to execute specified by file -.Ar script . -If the -.Ar script -argument is set to -.Dq - -the standard input is read instead. -.\" project-info -.It Cm project-info -Get the detailed information, including the script code from -.Ar project . -.\" project-list -.It Cm project-list -List all projects, excluding the script code. -.\" project-update -.It Cm project-update -Update an existing -.Ar project -by setting its new fields. The -.Ar key -argument should be one of the argument specified in the -.Cm project-add -command. For example, to update the description of a project one should -specify -.Dq desc -as -.Ar name -argument and a new description as -.Ar key . -.Pp -Example: -.Bd -literal -offset indent -scictl project-update example desc "New description" -.Ed -.\" worker-add -.It Cm worker-add -Create a new worker with -.Ar name -user identifier and an arbirary -.Ar desc -description. -.\" worker-list -.It Cm worker-list -List all workers present on the system. It does not indicate if those workers -are actually running. -.El -.\" SEE ALSO -.Sh SEE ALSO -.Xr sci 7 , -.Xr scid 8 , -.Xr sciwebd 8 , -.Xr sciworkerd 8
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/scid.8 Thu Aug 04 18:01:29 2022 +0200 @@ -0,0 +1,69 @@ +.\" +.\" 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 SCID 8 +.Os +.\" NAME +.Sh NAME +.Nm scid +.Nd main sci controller daemon +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm +.Op Fl f +.Op Fl d Ar database-file +.Op Fl t Ar theme-directory +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +program is the main controller daemon responsible of the database access and +web content. It opens it, creates if does not exist and then update its +content. +.Pp +After that, it opens a CGI/FastCGI service to get HTTP requests either from a +web browser or through the dedicated +.Xr scictl 1 +utility. +.Pp +Usually, you want to setup +.Nm +to run with the associated too +.Xr kfcgi 8 +or any other FastCGI spawner. +.Pp +It is part of the +.Xr sci 7 +continuous integration framework. +.Pp +Available options: +.Bl -tag +.It Fl f +Runs as FastCGI process. +.It Fl d Ar database-file +Use path specified +.Pa database-file +as alternative database location. +.It Fl t Ar theme-directory +Use +.Ar theme-directory +as theme to use. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr sci 7 , +.Xr scictl 8 , +.Xr sciworkerd 8
--- a/man/scid.8.in Thu Aug 04 17:47:19 2022 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ -.\" -.\" 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 June 30, 2021-2022 -.Dt SCID 8 -.Os -.\" NAME -.Sh NAME -.Nm scid -.Nd main sci controller daemon -.\" SYNOPSIS -.Sh SYNOPSIS -.Nm -.Op Fl f -.Op Fl d Ar database-file -.\" DESCRIPTION -.Sh DESCRIPTION -The -.Nm -program is the main controller daemon responsible of the database access and -web content. It opens it, creates if does not exist and then update its -content. -.Pp -After that, it opens a CGI/FastCGI service to get HTTP requests either from a -web browser or through the dedicated -.Xr scictl 1 -utility. -.Pp -It is part of the -.Xr sci 7 -continuous integration framework. -.Pp -Available options: -.Bl -tag -.It Fl f -Runs as FastCGI process. -.It Fl d Ar database-file -Use path specified -.Pa database-file -as alternative database location. -.El -.\" SEE ALSO -.Sh SEE ALSO -.Xr sci 7 , -.Xr scictl 8 , -.Xr sciworkerd 8
--- a/man/sciwebd.8.in Thu Aug 04 17:47:19 2022 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,151 +0,0 @@ -.\" -.\" 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 June 30, 2021-2022 -.Dt SCIWEBD 8 -.Os -.\" NAME -.Sh NAME -.Nm sciwebd -.Nd CGI/FastCGI interface for sci -.\" SYNOPSIS -.Sh SYNOPSIS -.Nm -.Op Fl f -.Op Fl s Ar socket-file -.Op Fl t Ar theme -.\" DESCRIPTION -.Sh DESCRIPTION -The -.Nm -daemon is a -.Xr kcgi 3 -based application to expose an HTTP interface for user statistics and a JSON API -for -.Xr sciworkerd 8 -daemons. It requires a HTTP server running as proxy to handle -requests into it. See below for example of configuration. -.Pp -It is part of the -.Xr sci 7 -continuous integration framework. -.Pp -The following options are available: -.Bl -tag -width "-s path" -.It Fl f -Runs as a FastCGI daemon. -.It Fl s Ar path -Connect to the UNIX local socket specified by -.Ar path . -.It Fl t Ar theme -Use -.Ar theme -as directory path for HTML pages. -.El -.\" CONFIGURATION -.Sh CONFIGURATION -The recommended way to use -.Nm -is to deploy using FastCGI. You can use the -.Xr kfcgi 8 -helper to spawn the process for you. -.Pp -Example: -.Bd -literal -offset Ds -kfcgi -p /var/www/sci -- scid -f -d sci.db -t siimple -.Ed -.Pp -Note: kfcgi chroot to the directory given, you must either statically link -scid at build time or deploy all required libraries. Also, themes directory -will need to be available in the chroot directory. In the above example, this -will effectively create a database -.Pa /var/www/sci/sci.db -and use the theme -.Pa /var/www/sci/siimple . -.Pp -Then, simply copy the desired theme into the directory. -.Bd -literal -offset Ds -cp -R @SHAREDIR@/sci/themes/siimple /var/www/sci -.Ed -.Pp -As an -.Em insecure -alternative, you can chroot to -.Pa / -to avoid static-linking and copying themes, using: -.Bd -literal -offset Ds -kfcgi -p / -- scid -f \e - -d /var/www/sci/sci.db \e - -t @SHAREDIR@/sci/themes/siimple -.Ed -.Pp -Both kfcgi invocations will create -.Pa /var/www/run/http.sock -with current user and group. Configure the web server to talk to that socket -and make sure it has appropriate file permissions otherwise see -.Fl u -option in -.Nm kfcgi . -See also the -.Xr kfcgi 8 -manual for more information. -.Pp -Next, configure the web server. -.Pp -Warning: at this moment, -.Nm -requires its own virtual host and can -.Em not -use a url. -.\" Server: nginx -.Ss Server: nginx -The nginx web server requires several parameters to run -.Nm . -.Bd -literal -server { - server_name sci.example.org; - listen 80; - - location / { - fastcgi_param QUERY_STRING query_string; - fastcgi_param REQUEST_METHOD $request_method; - fastcgi_param CONTENT_TYPE $content_type; - fastcgi_param CONTENT_LENGTH $content_length; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - fastcgi_param SCRIPT_NAME $fastcgi_script_name; - fastcgi_param PATH_INFO $document_uri; - fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; - fastcgi_param REQUEST_URI $request_uri; - fastcgi_param DOCUMENT_URI $document_uri; - fastcgi_param DOCUMENT_ROOT $document_root; - fastcgi_param SERVER_PROTOCOL $server_protocol; - fastcgi_param GATEWAY_INTERFACE CGI/1.1; - fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; - fastcgi_param REMOTE_ADDR $remote_addr; - fastcgi_param REMOTE_PORT $remote_port; - fastcgi_param SERVER_ADDR $server_addr; - fastcgi_param SERVER_PORT $server_port; - fastcgi_param SERVER_NAME $server_name; - fastcgi_param HTTPS $https; - fastcgi_pass unix:/var/www/run/httpd.sock; - } -} -.Ed -.\" SEE ALSO -.Sh SEE ALSO -.Xr sci 7 , -.Xr scictl 8 , -.Xr scid 8 , -.Xr sciworkerd 8
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/sciworkerd.8 Thu Aug 04 18:01:29 2022 +0200 @@ -0,0 +1,78 @@ +.\" +.\" 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 June 30, 2021-2022 +.Dt SCIWORKERD 8 +.Os +.\" NAME +.Sh NAME +.Nm sciworkerd +.Nd sci worker daemon +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm +.Op Fl m Ar maxbuilds +.Op Fl u Ar url +.Op Fl w Ar workername +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +daemon waits indefinitely for jobs to execute and send back their result. It +requires an access to +.Xr scid 8 +running. +.Pp +It is +.Em strongly +advised to run +.Nm +in a clean chroot environment, otherwise you can fetch untrusted scripts if the +remote +.Nm scid +gets compromised. +.Pp +It is part of the +.Xr sci 7 +continuous integration framework. +.Pp +The following options are available: +.Bl -tag +.It Fl m +Set the maximum number of parallel builds allowed to +.Ar maxbuilds . +Defaults: 4. +.It Fl u +Set the +.Ar url +for connecting to +.Xr scid 8 . +You can specify a scheme using +.Dq http:// +or +.Dq https:// . +Default: +.Dq localhost . +.It Fl w +Specify which worker this daemon should refer to using +.Ar worker +as worker name. Default: +.Dq default +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr sci 7 , +.Xr scictl 8 , +.Xr scid 8
--- a/man/sciworkerd.8.in Thu Aug 04 17:47:19 2022 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,72 +0,0 @@ -.\" -.\" 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 June 30, 2021-2022 -.Dt SCIWORKERD 8 -.Os -.\" NAME -.Sh NAME -.Nm sciworkerd -.Nd sci worker daemon -.\" SYNOPSIS -.Sh SYNOPSIS -.Nm -.Op Fl m Ar maxbuilds -.Op Fl u Ar url -.Op Fl w Ar workername -.\" DESCRIPTION -.Sh DESCRIPTION -The -.Nm -daemon waits indefinitely for jobs to execute and send back their result. It -requires an access to -.Xr sciwebd 8 -running and transitively a -.Xr scid 8 -daemon running as well. -.Pp -It is part of the -.Xr sci 7 -continuous integration framework. -.Pp -The following options are available: -.Bl -tag -.It Fl m -Set the maximum number of parallel builds allowed to -.Ar maxbuilds . -Defaults: 4. -.It Fl u -Set the -.Ar url -for connecting to -.Xr sciwebd 8 . -You can specify a scheme using -.Dq http:// -or -.Dq https:// . -Default: -.Dq localhost . -.It Fl w -Specify which worker this daemon should refer to using -.Ar worker -as worker name. Default: -.Dq default -.El -.\" SEE ALSO -.Sh SEE ALSO -.Xr sci 7 , -.Xr scictl 8 , -.Xr scid 8 , -.Xr sciwebd 8 ,