Mercurial > sci

comparison man/sci.7 @ 64:562372396019

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: improve manual pages and documentation
author David Demelier <markand@malikania.fr>
date Thu, 18 Aug 2022 20:17:18 +0200
parents 084dee2bef50
children 5076be758687
comparison
equal deleted inserted replaced
63:67470b67e460 64:562372396019
69 .\" ENTITIES 69 .\" ENTITIES
70 .Sh ENTITIES 70 .Sh ENTITIES
71 The process handle different kind of entities in the database. 71 The process handle different kind of entities in the database.
72 .\" PROJECTS 72 .\" PROJECTS
73 .Ss PROJECTS 73 .Ss PROJECTS
74 A project is an user description of what to be automated and tested. It has a 74 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 75 name, description, project URL and a script to execute. They can be created
76 using the 76 using the
77 .Cm project-add 77 .Cm project-add
78 command from 78 command from
79 .Nm scictl . 79 .Nm scictl .
95 A job result is the detail about a job ran by a worker for a specific project. 95 A job result is the detail about a job ran by a worker for a specific project.
96 If a job exists for one project and there are four workers on the user 96 If a job exists for one project and there are four workers on the user
97 installation, there will be four job results. It has an exit code (got from the 97 installation, there will be four job results. It has an exit code (got from the
98 user script), a log console (capture from standard output and error) and a 98 user script), a log console (capture from standard output and error) and a
99 timestamp when it was started. 99 timestamp when it was started.
100 .\" GETTING STARTED
101 .Sh GETTING STARTED
102 To setup the
103 .Nm
104 framework you need at least:
105 .Bl -enum
106 .It
107 A daemon
108 .Xr scid 8
109 running and accessible remotely.
110 .It
111 One or more
112 .Xr sciworkerd 8
113 running on a machine that can access
114 .Xr scid 8 .
115 .It
116 Add some projects and register those workers using
117 .Xr scictl 8
118 utility.
119 .El
120 .\" Setup scid
121 .Ss Setup scid
122 The
123 .Xr scid 8
124 daemon does not require much configuration, you can specify the database file
125 to use with its appropriate options. Otherwise, you can simply run the daemon
126 with no arguments. It will initialize the database and generate a default API
127 key that
128 .Xr scictl 8
129 and
130 .Xr sciworkerd 8
131 require to perform requests. Use the
132 .Cm api-get
133 command to get that key.
134 .Bd -literal -offset indent
135 $ scid
136 Or
137 $ scid -d /var/db/scid.db
138 .Ed
139 .Pp
140 Retrieve the stored key:
141 .Bd -literal -offset indent
142 $ scid api-get
143 1234567890secretABCDEF
144 .Ed
145 .Pp
146 Both
147 .Xr scictl 8
148 and
149 .Xr sciworkerd 8
150 understand the same options and environment variables. So let's set the API key
151 as environment variable for the next chapters.
152 .Bd -literal -offset indent
153 export SCI_API_KEY=1234567890secretABCDEF
154 .Ed
155 .Pp
156 If you run
157 .Xr scid 8
158 on a machine that is not on the same as the worker, you also
159 need to specify the
160 .Ev SCI_API_URL
161 environment variable.
162 .Bd -literal -offset indent
163 export SCI_API_URL=http://127.0.0.1
164 .Ed
165 .\" Setup a worker
166 .Ss Setup a worker
167 To register a worker, use the
168 .Cm worker-add
169 command from
170 .Xr scictl 8
171 utility.
172 .Bd -literal -offset indent
173 scictl worker-add openbsd "OpenBSD 7.2"
174 .Ed
175 .Pp
176 It is
177 .Em strongly
178 advised to run a
179 .Xr sciworkerd 8
180 instance inside a chroot or a virtual machine, remember that it will fetch the
181 script code remotely!
182 .Bd -literal -offset indent
183 $ sciworkerd
184 Or
185 $ sciworkerd -j2
186 .Ed
187 .Pp
188 Please make sure to read
189 .Xr sciworkerd 8
190 manual page for more tuning options.
191 .\" Register a project
192 .Ss Register a project
193 Create a project named
194 .Em hello
195 with a description, URL, a homepage and a script file to execute. The script
196 code can be of any language but it's advised that you stick with some
197 interpreted language as many different workers may execute it.
198 .Bd -literal -offset indent
199 $ scictl project-add hello "Hello World" "http://hello.org" "hello.sh"
200 .Ed
201 .\" Register jobs
202 .Ss Register jobs
203 Now, you may want to register a job that will be executed for every worker.
204 .Pp
205 Use the
206 .Cm job-add
207 command from
208 .Xr scictl 8
209 utility. The
210 .Ar tag
211 argument is the unique argument that will be passed to the script code. In our
212 case we will assume it's a revision from a SCM repository.
213 .Bd -literal -offset indent
214 $ scictl job-add hello 67470b67e460
215 .Ed
216 .Pp
217 And after that, any
218 .Xr sciworkerd 8
219 instance will fetch the job, run it and send the result.
100 .\" SEE ALSO 220 .\" SEE ALSO
101 .Sh SEE ALSO 221 .Sh SEE ALSO
102 .Xr scictl 8 , 222 .Xr scictl 8 ,
103 .Xr scid 8 , 223 .Xr scid 8 ,
104 .Xr sciworkerd 8 224 .Xr sciworkerd 8