Fossil SCM
Expanded the "Standalone server" section of www/server.wiki to add more examples. Also fixed a few grammar problems elsewhere in the doc.
Commit
f153777f3efcf65c2595b104fbca109f203ba356e7aff591f4d2c60a0b9cc962
Parent
355c16a528d03e7…
1 file changed
+34
-13
+34
-13
| --- www/server.wiki | ||
| +++ www/server.wiki | ||
| @@ -63,16 +63,37 @@ | ||
| 63 | 63 | <li>anyone who visits this URL is treated as the all-powerful Setup |
| 64 | 64 | user, which is why the first difference exists. |
| 65 | 65 | <li>"ui" launches a local web browser pointed at this URL. |
| 66 | 66 | </ul> |
| 67 | 67 | |
| 68 | -If one of the commands above is run from within an open checkout, | |
| 69 | -then the <i>REPOSITORY</i> argument can be omitted and the checkout is used as | |
| 70 | -the repository. | |
| 68 | +You can omit the <i>REPOSITORY</i> argument if you run one of the above | |
| 69 | +commands from within a Fossil checkout directory to serve that | |
| 70 | +repository: | |
| 71 | + | |
| 72 | +<blockquote><pre> | |
| 73 | +$ fossil ui # or... | |
| 74 | +$ fossil serve | |
| 75 | +</pre></blockquote> | |
| 76 | + | |
| 77 | +Note that you can abbreviate Fossil sub-commands, as long as they are | |
| 78 | +unambiguous. "<tt>server</tt>" can currently be as short as | |
| 79 | +"<tt>ser</tt>". | |
| 80 | + | |
| 81 | +As a more complicated example, you can serve a directory containing | |
| 82 | +multiple <tt>*.fossil</tt> files like so: | |
| 83 | + | |
| 84 | +<blockquote><pre> | |
| 85 | +$ fossil server --port 9000 --repolist /path/to/repo/dir | |
| 86 | +</pre></blockquote> | |
| 87 | + | |
| 88 | +There is an [/file/tools/fslsrv | example script] in the Fossil | |
| 89 | +distribution that wraps <tt>fossil server</tt> to produce more | |
| 90 | +complicated effects. Feel free to take it, study it, and modify it to | |
| 91 | +suit your local needs. | |
| 71 | 92 | |
| 72 | -Both commands have additional command-line options that can be used to refine | |
| 73 | -their behavior. See the [/help/server|online documentation] for an overview. | |
| 93 | +See the [/help/server|online documentation] for more information on the | |
| 94 | +options and arguments you can give to these commands. | |
| 74 | 95 | </blockquote> |
| 75 | 96 | |
| 76 | 97 | |
| 77 | 98 | <h2 id="inetd">Fossil as an inetd/xinetd service</h2> |
| 78 | 99 | |
| @@ -241,21 +262,21 @@ | ||
| 241 | 262 | } |
| 242 | 263 | </pre></blockquote> |
| 243 | 264 | |
| 244 | 265 | Note that Fossil requires the SCRIPT_NAME variable |
| 245 | 266 | in order to function properly, but Nginx does not provide this |
| 246 | -variable by default. | |
| 247 | -So it is necessary to provide the SCRIPT_NAME parameter in the configuration. | |
| 267 | +variable by default, | |
| 268 | +so it is necessary to provide the SCRIPT_NAME parameter in the configuration. | |
| 248 | 269 | Failure to do this will cause Fossil to return an error. |
| 249 | 270 | |
| 250 | 271 | All of the features of the stand-alone server mode described above, |
| 251 | 272 | such as the ability to serve a directory full of Fossil repositories |
| 252 | 273 | rather than just a single repository, work the same way in SCGI mode. |
| 253 | 274 | |
| 254 | 275 | For security, it is probably a good idea to add the --localhost option |
| 255 | 276 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 256 | -off-site connections. And one might want to specify the listening TCP port | |
| 277 | +off-site connections. One might also want to specify the listening TCP port | |
| 257 | 278 | number, rather than letting Fossil choose one for itself, just to avoid |
| 258 | 279 | ambiguity. A typical command to start a Fossil SCGI server |
| 259 | 280 | would be something like this: |
| 260 | 281 | |
| 261 | 282 | <blockquote><pre> |
| @@ -280,12 +301,12 @@ | ||
| 280 | 301 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 281 | 302 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 282 | 303 | addition to Fossil (and including some very high-traffic sites such |
| 283 | 304 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 284 | 305 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 285 | -normally takes less than 10 milliseconds of CPU time to complete. So | |
| 286 | -requests can be arriving at a continuous rate of 20 or more per second | |
| 306 | +normally takes less than 10 milliseconds of CPU time to complete, so | |
| 307 | +requests can be arriving at a continuous rate of 20 or more per second, | |
| 287 | 308 | and the CPU can still be mostly idle. |
| 288 | 309 | |
| 289 | 310 | However, there are some Fossil web pages that can consume large |
| 290 | 311 | amounts of CPU time, especially on repositories with a large number |
| 291 | 312 | of files or with long revision histories. High CPU usage pages include |
| @@ -317,15 +338,15 @@ | ||
| 317 | 338 | "chown" the cache database (which is a separate file in the same directory |
| 318 | 339 | and with the same name as the repository but with the suffix changed to ".cache") |
| 319 | 340 | to give it write permission for the userid of the webserver. |
| 320 | 341 | |
| 321 | 342 | To activate the server load control feature |
| 322 | -visit the /Admin/Access setup page in the administrative web | |
| 323 | -interface and in the "<b>Server Load Average Limit</b>" box | |
| 343 | +visit the Admin → Access setup page in the administrative web | |
| 344 | +interface; in the "<b>Server Load Average Limit</b>" box | |
| 324 | 345 | enter the load average threshold above which "503 Server |
| 325 | 346 | Overload" replies will be issued for expensive requests. On the |
| 326 | -self-host Fossil server, that value is set to 1.5. But you could easily | |
| 347 | +self-hosting Fossil server, that value is set to 1.5, but you could easily | |
| 327 | 348 | set it higher on a multi-core server. |
| 328 | 349 | |
| 329 | 350 | The maximum load average can also be set on the command line using |
| 330 | 351 | commands like this: |
| 331 | 352 | <blockquote><pre> |
| 332 | 353 |
| --- www/server.wiki | |
| +++ www/server.wiki | |
| @@ -63,16 +63,37 @@ | |
| 63 | <li>anyone who visits this URL is treated as the all-powerful Setup |
| 64 | user, which is why the first difference exists. |
| 65 | <li>"ui" launches a local web browser pointed at this URL. |
| 66 | </ul> |
| 67 | |
| 68 | If one of the commands above is run from within an open checkout, |
| 69 | then the <i>REPOSITORY</i> argument can be omitted and the checkout is used as |
| 70 | the repository. |
| 71 | |
| 72 | Both commands have additional command-line options that can be used to refine |
| 73 | their behavior. See the [/help/server|online documentation] for an overview. |
| 74 | </blockquote> |
| 75 | |
| 76 | |
| 77 | <h2 id="inetd">Fossil as an inetd/xinetd service</h2> |
| 78 | |
| @@ -241,21 +262,21 @@ | |
| 241 | } |
| 242 | </pre></blockquote> |
| 243 | |
| 244 | Note that Fossil requires the SCRIPT_NAME variable |
| 245 | in order to function properly, but Nginx does not provide this |
| 246 | variable by default. |
| 247 | So it is necessary to provide the SCRIPT_NAME parameter in the configuration. |
| 248 | Failure to do this will cause Fossil to return an error. |
| 249 | |
| 250 | All of the features of the stand-alone server mode described above, |
| 251 | such as the ability to serve a directory full of Fossil repositories |
| 252 | rather than just a single repository, work the same way in SCGI mode. |
| 253 | |
| 254 | For security, it is probably a good idea to add the --localhost option |
| 255 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 256 | off-site connections. And one might want to specify the listening TCP port |
| 257 | number, rather than letting Fossil choose one for itself, just to avoid |
| 258 | ambiguity. A typical command to start a Fossil SCGI server |
| 259 | would be something like this: |
| 260 | |
| 261 | <blockquote><pre> |
| @@ -280,12 +301,12 @@ | |
| 280 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 281 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 282 | addition to Fossil (and including some very high-traffic sites such |
| 283 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 284 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 285 | normally takes less than 10 milliseconds of CPU time to complete. So |
| 286 | requests can be arriving at a continuous rate of 20 or more per second |
| 287 | and the CPU can still be mostly idle. |
| 288 | |
| 289 | However, there are some Fossil web pages that can consume large |
| 290 | amounts of CPU time, especially on repositories with a large number |
| 291 | of files or with long revision histories. High CPU usage pages include |
| @@ -317,15 +338,15 @@ | |
| 317 | "chown" the cache database (which is a separate file in the same directory |
| 318 | and with the same name as the repository but with the suffix changed to ".cache") |
| 319 | to give it write permission for the userid of the webserver. |
| 320 | |
| 321 | To activate the server load control feature |
| 322 | visit the /Admin/Access setup page in the administrative web |
| 323 | interface and in the "<b>Server Load Average Limit</b>" box |
| 324 | enter the load average threshold above which "503 Server |
| 325 | Overload" replies will be issued for expensive requests. On the |
| 326 | self-host Fossil server, that value is set to 1.5. But you could easily |
| 327 | set it higher on a multi-core server. |
| 328 | |
| 329 | The maximum load average can also be set on the command line using |
| 330 | commands like this: |
| 331 | <blockquote><pre> |
| 332 |
| --- www/server.wiki | |
| +++ www/server.wiki | |
| @@ -63,16 +63,37 @@ | |
| 63 | <li>anyone who visits this URL is treated as the all-powerful Setup |
| 64 | user, which is why the first difference exists. |
| 65 | <li>"ui" launches a local web browser pointed at this URL. |
| 66 | </ul> |
| 67 | |
| 68 | You can omit the <i>REPOSITORY</i> argument if you run one of the above |
| 69 | commands from within a Fossil checkout directory to serve that |
| 70 | repository: |
| 71 | |
| 72 | <blockquote><pre> |
| 73 | $ fossil ui # or... |
| 74 | $ fossil serve |
| 75 | </pre></blockquote> |
| 76 | |
| 77 | Note that you can abbreviate Fossil sub-commands, as long as they are |
| 78 | unambiguous. "<tt>server</tt>" can currently be as short as |
| 79 | "<tt>ser</tt>". |
| 80 | |
| 81 | As a more complicated example, you can serve a directory containing |
| 82 | multiple <tt>*.fossil</tt> files like so: |
| 83 | |
| 84 | <blockquote><pre> |
| 85 | $ fossil server --port 9000 --repolist /path/to/repo/dir |
| 86 | </pre></blockquote> |
| 87 | |
| 88 | There is an [/file/tools/fslsrv | example script] in the Fossil |
| 89 | distribution that wraps <tt>fossil server</tt> to produce more |
| 90 | complicated effects. Feel free to take it, study it, and modify it to |
| 91 | suit your local needs. |
| 92 | |
| 93 | See the [/help/server|online documentation] for more information on the |
| 94 | options and arguments you can give to these commands. |
| 95 | </blockquote> |
| 96 | |
| 97 | |
| 98 | <h2 id="inetd">Fossil as an inetd/xinetd service</h2> |
| 99 | |
| @@ -241,21 +262,21 @@ | |
| 262 | } |
| 263 | </pre></blockquote> |
| 264 | |
| 265 | Note that Fossil requires the SCRIPT_NAME variable |
| 266 | in order to function properly, but Nginx does not provide this |
| 267 | variable by default, |
| 268 | so it is necessary to provide the SCRIPT_NAME parameter in the configuration. |
| 269 | Failure to do this will cause Fossil to return an error. |
| 270 | |
| 271 | All of the features of the stand-alone server mode described above, |
| 272 | such as the ability to serve a directory full of Fossil repositories |
| 273 | rather than just a single repository, work the same way in SCGI mode. |
| 274 | |
| 275 | For security, it is probably a good idea to add the --localhost option |
| 276 | to the [/help/server|fossil server] command to prevent Fossil from accepting |
| 277 | off-site connections. One might also want to specify the listening TCP port |
| 278 | number, rather than letting Fossil choose one for itself, just to avoid |
| 279 | ambiguity. A typical command to start a Fossil SCGI server |
| 280 | would be something like this: |
| 281 | |
| 282 | <blockquote><pre> |
| @@ -280,12 +301,12 @@ | |
| 301 | The Fossil [./selfhost.wiki | self-hosting server] is a 1/24th slice VM at |
| 302 | [http://www.linode.com | Linode.com] hosting 65 other repositories in |
| 303 | addition to Fossil (and including some very high-traffic sites such |
| 304 | as [http://www.sqlite.org] and [http://system.data.sqlite.org]) and |
| 305 | it has a typical load of 0.05 to 0.1. A single HTTP request to Fossil |
| 306 | normally takes less than 10 milliseconds of CPU time to complete, so |
| 307 | requests can be arriving at a continuous rate of 20 or more per second, |
| 308 | and the CPU can still be mostly idle. |
| 309 | |
| 310 | However, there are some Fossil web pages that can consume large |
| 311 | amounts of CPU time, especially on repositories with a large number |
| 312 | of files or with long revision histories. High CPU usage pages include |
| @@ -317,15 +338,15 @@ | |
| 338 | "chown" the cache database (which is a separate file in the same directory |
| 339 | and with the same name as the repository but with the suffix changed to ".cache") |
| 340 | to give it write permission for the userid of the webserver. |
| 341 | |
| 342 | To activate the server load control feature |
| 343 | visit the Admin → Access setup page in the administrative web |
| 344 | interface; in the "<b>Server Load Average Limit</b>" box |
| 345 | enter the load average threshold above which "503 Server |
| 346 | Overload" replies will be issued for expensive requests. On the |
| 347 | self-hosting Fossil server, that value is set to 1.5, but you could easily |
| 348 | set it higher on a multi-core server. |
| 349 | |
| 350 | The maximum load average can also be set on the command line using |
| 351 | commands like this: |
| 352 | <blockquote><pre> |
| 353 |