# HG changeset patch # User David Demelier # Date 1660846638 -7200 # Node ID 562372396019fb9bccee777e0d2cd76f93c80f4b # Parent 67470b67e4609cfedb290bef4c48021419fc52a7 misc: improve manual pages and documentation diff -r 67470b67e460 -r 562372396019 man/sci.7 --- a/man/sci.7 Thu Aug 18 12:29:28 2022 +0200 +++ b/man/sci.7 Thu Aug 18 20:17:18 2022 +0200 @@ -71,7 +71,7 @@ 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 +A project is a 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 @@ -97,6 +97,126 @@ 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. +.\" GETTING STARTED +.Sh GETTING STARTED +To setup the +.Nm +framework you need at least: +.Bl -enum +.It +A daemon +.Xr scid 8 +running and accessible remotely. +.It +One or more +.Xr sciworkerd 8 +running on a machine that can access +.Xr scid 8 . +.It +Add some projects and register those workers using +.Xr scictl 8 +utility. +.El +.\" Setup scid +.Ss Setup scid +The +.Xr scid 8 +daemon does not require much configuration, you can specify the database file +to use with its appropriate options. Otherwise, you can simply run the daemon +with no arguments. It will initialize the database and generate a default API +key that +.Xr scictl 8 +and +.Xr sciworkerd 8 +require to perform requests. Use the +.Cm api-get +command to get that key. +.Bd -literal -offset indent +$ scid +Or +$ scid -d /var/db/scid.db +.Ed +.Pp +Retrieve the stored key: +.Bd -literal -offset indent +$ scid api-get +1234567890secretABCDEF +.Ed +.Pp +Both +.Xr scictl 8 +and +.Xr sciworkerd 8 +understand the same options and environment variables. So let's set the API key +as environment variable for the next chapters. +.Bd -literal -offset indent +export SCI_API_KEY=1234567890secretABCDEF +.Ed +.Pp +If you run +.Xr scid 8 +on a machine that is not on the same as the worker, you also +need to specify the +.Ev SCI_API_URL +environment variable. +.Bd -literal -offset indent +export SCI_API_URL=http://127.0.0.1 +.Ed +.\" Setup a worker +.Ss Setup a worker +To register a worker, use the +.Cm worker-add +command from +.Xr scictl 8 +utility. +.Bd -literal -offset indent +scictl worker-add openbsd "OpenBSD 7.2" +.Ed +.Pp +It is +.Em strongly +advised to run a +.Xr sciworkerd 8 +instance inside a chroot or a virtual machine, remember that it will fetch the +script code remotely! +.Bd -literal -offset indent +$ sciworkerd +Or +$ sciworkerd -j2 +.Ed +.Pp +Please make sure to read +.Xr sciworkerd 8 +manual page for more tuning options. +.\" Register a project +.Ss Register a project +Create a project named +.Em hello +with a description, URL, a homepage and a script file to execute. The script +code can be of any language but it's advised that you stick with some +interpreted language as many different workers may execute it. +.Bd -literal -offset indent +$ scictl project-add hello "Hello World" "http://hello.org" "hello.sh" +.Ed +.\" Register jobs +.Ss Register jobs +Now, you may want to register a job that will be executed for every worker. +.Pp +Use the +.Cm job-add +command from +.Xr scictl 8 +utility. The +.Ar tag +argument is the unique argument that will be passed to the script code. In our +case we will assume it's a revision from a SCM repository. +.Bd -literal -offset indent +$ scictl job-add hello 67470b67e460 +.Ed +.Pp +And after that, any +.Xr sciworkerd 8 +instance will fetch the job, run it and send the result. .\" SEE ALSO .Sh SEE ALSO .Xr scictl 8 , diff -r 67470b67e460 -r 562372396019 man/scictl.8 --- a/man/scictl.8 Thu Aug 18 12:29:28 2022 +0200 +++ b/man/scictl.8 Thu Aug 18 20:17:18 2022 +0200 @@ -69,6 +69,26 @@ and SCM integration to add new jobs to execute. It is also used as administrative utility to create projects and workers. .Pp +The following options are available +.Em before +the command name: +.Bl -tag +.It Fl k Ar key +Set the API authentication to +.Ar key . +.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 . +.El +.Pp It is part of the .Xr sci 7 continuous integration framework. diff -r 67470b67e460 -r 562372396019 man/sciworkerd.8 --- a/man/sciworkerd.8 Thu Aug 18 12:29:28 2022 +0200 +++ b/man/sciworkerd.8 Thu Aug 18 20:17:18 2022 +0200 @@ -23,7 +23,9 @@ .\" SYNOPSIS .Sh SYNOPSIS .Nm -.Op Fl m Ar maxbuilds +.Op Fl j Ar maxbuilds +.Op Fl k Ar key +.Op Fl t Ar timeout .Op Fl u Ar url .Op Fl w Ar workername .\" DESCRIPTION @@ -50,10 +52,17 @@ .Pp The following options are available: .Bl -tag -.It Fl m +.It Fl j Set the maximum number of parallel builds allowed to .Ar maxbuilds . Defaults: 4. +.It Fl k Ar key +Set the API authentication to +.Ar key . +.It Fl t Ar timeout +Defines in seconds the +.Ar timeout +before a job will be killed. .It Fl u Set the .Ar url @@ -85,6 +94,8 @@ .Dq https . .It Ev SCI_API_KEY Secret API key to perform requests. +.It Ev SCI_WORKER +Defines the worker name to connect as. .El .\" SEE ALSO .Sh SEE ALSO diff -r 67470b67e460 -r 562372396019 sciworkerd/main.c --- a/sciworkerd/main.c Thu Aug 18 12:29:28 2022 +0200 +++ b/sciworkerd/main.c Thu Aug 18 20:17:18 2022 +0200 @@ -45,7 +45,7 @@ env(); opterr = 0; - while ((ch = util_getopt(argc, argv, "k:j:t:u:w:")) != -1) { + while ((ch = util_getopt(argc, argv, "j:k:t:u:w:")) != -1) { switch (ch) { case 'j': if ((val = atoi(optarg)) > 0)