Mercurial > sci

comparison man/sci.7 @ 66:5076be758687 0.1.0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: update before 0.1.0 release
author David Demelier <markand@malikania.fr>
date Sat, 20 Aug 2022 10:36:55 +0200
parents 562372396019
children 71cd8447e3a4
comparison
equal deleted inserted replaced
65:471410c90954 66:5076be758687
43 The communication workflow is: 43 The communication workflow is:
44 .Bd -literal 44 .Bd -literal
45 o ---- scictl 45 o ---- scictl
46 / 46 /
47 scid (HTTP) o 47 scid (HTTP) o
48 \\ 48 | \\
49 o ---- sciworkerd 49 | o ---- sciworkerd
50 SQLite
50 .Ed 51 .Ed
51 .Pp 52 .Pp
52 The 53 The
53 .Nm scid 54 .Nm scid
54 daemon is the unique access to the SQLite database and simply take requests 55 daemon is the unique access to the SQLite database and simply take requests
66 querying 67 querying
67 .Nm scid 68 .Nm scid
68 and output their result. 69 and output their result.
69 .\" ENTITIES 70 .\" ENTITIES
70 .Sh ENTITIES 71 .Sh ENTITIES
71 The process handle different kind of entities in the database. 72 The process handles different kind of entities in the database.
72 .\" PROJECTS 73 .\" PROJECTS
73 .Ss PROJECTS 74 .Ss PROJECTS
74 A project is a user description of what to be automated and tested. It has a 75 A project is a user description of what to be automated and tested. It has a
75 name, description, project URL and a script to execute. They can be created 76 name, description, project URL and a script to execute. They can be created
76 using the 77 using the
129 and 130 and
130 .Xr sciworkerd 8 131 .Xr sciworkerd 8
131 require to perform requests. Use the 132 require to perform requests. Use the
132 .Cm api-get 133 .Cm api-get
133 command to get that key. 134 command to get that key.
134 .Bd -literal -offset indent 135 .Pp
135 $ scid 136 The
137 .Xr scid 8
138 program isn't a daemon by itself but a CGI or FastCGI process which needs to be
139 coupled with a dedicated web server. For the example let's use nginx and the
140 .Xr kfcgi 8
141 utility to spawn our FastCGI process.
142 .Pp
143 Configure the nginx server to include at least the following code snippet for a
144 specific virtual host (the
145 .Xr scid 8
146 process explicitly requires its own virtual host).
147 .Bd -literal -offset indent
148 server {
149 server_name sci.myhostname.fr;
150 listen 80;
151
152 location / {
153 fastcgi_param QUERY_STRING query_string;
154 fastcgi_param REQUEST_METHOD $request_method;
155 fastcgi_param CONTENT_TYPE $content_type;
156 fastcgi_param CONTENT_LENGTH $content_length;
157 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
158 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
159 fastcgi_param PATH_INFO $document_uri;
160 fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
161 fastcgi_param REQUEST_URI $request_uri;
162 fastcgi_param DOCUMENT_URI $document_uri;
163 fastcgi_param DOCUMENT_ROOT $document_root;
164 fastcgi_param SERVER_PROTOCOL $server_protocol;
165 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
166 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
167 fastcgi_param REMOTE_ADDR $remote_addr;
168 fastcgi_param REMOTE_PORT $remote_port;
169 fastcgi_param SERVER_ADDR $server_addr;
170 fastcgi_param SERVER_PORT $server_port;
171 fastcgi_param SERVER_NAME $server_name;
172 fastcgi_param HTTPS $https;
173 fastcgi_pass unix:/var/www/run/httpd.sock;
174 }
175 }
176 .Ed
177 .Pp
178 Now, start the process using
179 .Xr kfcgi 8 .
180 It is recommended though, that the process lives in a clean chroot but in the
181 example we will skip that because
182 .Xr scid 8
183 cannot be built as static binary yet, you could as an alternative setup a
184 chroot where all required libraries are available in order to run
185 .Xr scid 8
186 inside of it.
187 .Pp
188 We will assume that the webserver is running with
189 .Em www
190 user and group which is the default also used with
191 .Xr kfcgi 8
192 utility. The webserver must have read/write access to the UNIX socket generated
193 with
194 .Xr kfcgi 8 .
195 .Pp
196 This command needs to be ran as root but it will drop privileges to
197 appropriate users and groups. See
198 .Xr kfcgi 8
199 for more details.
200 .Bd -literal -offset indent
201 # kfcgi -p / -- scid -f
136 Or 202 Or
137 $ scid -d /var/db/scid.db 203 # kfcgi -p / -u www -U www -- scid -f -d /path/to/sci.db -t /path/to/theme
138 .Ed 204 Or if you have a functional chroot (scid path is relative to it)
139 .Pp 205 # kfcgi -p /srv/sci -- /usr/bin/scid -f
140 Retrieve the stored key: 206 .Ed
207 .Pp
208 Make sure that
209 .Xr scid 8
210 get read/write access to the default database path if you're not using the
211 .Fl d
212 option. Also don't forget the
213 .Fl f
214 option which indicates the process to run as FastCGI rather than plain CGI.
215 .Pp
216 If the command succeeded, Retrieve the stored key:
141 .Bd -literal -offset indent 217 .Bd -literal -offset indent
142 $ scid api-get 218 $ scid api-get
143 1234567890secretABCDEF 219 1234567890secretABCDEF
144 .Ed 220 .Ed
145 .Pp 221 .Pp
179 .Xr sciworkerd 8 255 .Xr sciworkerd 8
180 instance inside a chroot or a virtual machine, remember that it will fetch the 256 instance inside a chroot or a virtual machine, remember that it will fetch the
181 script code remotely! 257 script code remotely!
182 .Bd -literal -offset indent 258 .Bd -literal -offset indent
183 $ sciworkerd 259 $ sciworkerd
184 Or 260 Or more secure alternative
185 $ sciworkerd -j2 261 # chroot /src/sci /usr/bin/sciworkerd -j2
186 .Ed 262 .Ed
187 .Pp 263 .Pp
188 Please make sure to read 264 Please make sure to read
189 .Xr sciworkerd 8 265 .Xr sciworkerd 8
190 manual page for more tuning options. 266 manual page for more tuning options.
214 $ scictl job-add hello 67470b67e460 290 $ scictl job-add hello 67470b67e460
215 .Ed 291 .Ed
216 .Pp 292 .Pp
217 And after that, any 293 And after that, any
218 .Xr sciworkerd 8 294 .Xr sciworkerd 8
219 instance will fetch the job, run it and send the result. 295 instance will fetch the job, run it and send the result. It is best used with
296 your SCM to add automatic job when pushing changes.
297 .Pp
298 Note: Jobs that are created before the registration of a worker won't be
299 executed as it would create a high number of jobs to be performed each time you
300 create a new worker.
220 .\" SEE ALSO 301 .\" SEE ALSO
221 .Sh SEE ALSO 302 .Sh SEE ALSO
222 .Xr scictl 8 , 303 .Xr scictl 8 ,
223 .Xr scid 8 , 304 .Xr scid 8 ,
224 .Xr sciworkerd 8 305 .Xr sciworkerd 8