Fossil SCM
Reworked the discussion of "fossil server" in the Quick Start to remove redundant discussion of "fossil ui" mode, previously covered. Moved some things up into that section as a result. The two modes are now treated independently, on purpose; the fact that they're implemented by a lot of shared code is an internal implementation detail, not something we need to make a point of in the Quick Start doc.
Commit
6a2fee8fd4701601d52c05c21b57eed4197f2113a98c96b43022c883d230d2a5
Parent
9c07d8a3a5cf06a…
1 file changed
+36
-42
+36
-42
| --- www/quickstart.wiki | ||
| +++ www/quickstart.wiki | ||
| @@ -322,34 +322,39 @@ | ||
| 322 | 322 | |
| 323 | 323 | This will get you started on identifying checkins. The |
| 324 | 324 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 325 | 325 | how timestamps can also be used. |
| 326 | 326 | |
| 327 | -<h2 id="config">Configuring Your Local Repository</h2> | |
| 327 | +<h2 id="config">Accessing Your Local Repository's Web User Interface</h2> | |
| 328 | 328 | |
| 329 | -When you create a new repository, either by cloning an existing | |
| 330 | -project or create a new project of your own, you usually want to do some | |
| 331 | -local configuration. This is most easily accomplished using the web-server | |
| 332 | -that is built into Fossil, like so: | |
| 329 | +After you create a new repository, you usually want to do some local | |
| 330 | +configuration. This is most easily accomplished by firing up the Fossil | |
| 331 | +UI: | |
| 333 | 332 | |
| 334 | 333 | <pre> |
| 335 | 334 | <b>fossil ui</b> <i>repository-filename</i> |
| 336 | 335 | </pre> |
| 337 | 336 | |
| 338 | 337 | You can shorten that to just [/help/ui | <b>fossil ui</b>] |
| 339 | 338 | if you are inside a checked-out local tree. |
| 340 | 339 | |
| 341 | -After the internal web server starts, Fossil automatically launches your | |
| 342 | -default web browser, pointed at itself. You may override that default so: | |
| 340 | +This command starts an internal web server, after which Fossil | |
| 341 | +automatically launches your default browser, pointed at itself, | |
| 342 | +presenting a special view of the repository, its web user interface. | |
| 343 | + | |
| 344 | +You may override Fossil's logic for selecting the default browser so: | |
| 343 | 345 | |
| 344 | 346 | <pre> |
| 345 | 347 | <b>fossil setting web-browser</b> <i>path-to-web-browser</i> |
| 346 | 348 | </pre> |
| 347 | 349 | |
| 348 | -Fossil binds this web server to the IP loopback address (127.0.0.1) | |
| 349 | -which it treats specially when launched this way, bypassing all user | |
| 350 | -controls. Why is that a good idea, you ask? Because it is a safe | |
| 350 | +When launched this way, Fossil binds its internal web server to the IP | |
| 351 | +loopback address, 127.0.0.1, which it treats specially, bypassing all | |
| 352 | +user controls, effectively giving visitors the | |
| 353 | +[./caps/admin-v-setup.md#apsu | all-powerful Setup capabliity]. | |
| 354 | + | |
| 355 | +Why is that a good idea, you ask? Because it is a safe | |
| 351 | 356 | presumption that only someone with direct file access to the repository |
| 352 | 357 | database file could be using the resulting web interface. Anyone who can |
| 353 | 358 | modify the repo DB directly could give themselves any and all access |
| 354 | 359 | with a SQL query, or even by direct file manipulation; no amount of |
| 355 | 360 | access control matters to such a user. |
| @@ -480,55 +485,44 @@ | ||
| 480 | 485 | level of undo/redo. |
| 481 | 486 | |
| 482 | 487 | |
| 483 | 488 | <h2 id="server">Setting Up A Server</h2> |
| 484 | 489 | |
| 485 | -Fossil can act as a stand-alone web server using one of these | |
| 486 | -commands: | |
| 490 | +In addition to the inward-facing <b>fossil ui</b> mode covered [#config | |
| 491 | +| above], Fossil can also act as an outward-facing web server: | |
| 487 | 492 | |
| 488 | 493 | <pre> |
| 489 | 494 | <b>[/help/server | fossil server]</b> <i>repository-filename</i> |
| 490 | -<b>[/help/ui | fossil ui]</b> <i>repository-filename</i> | |
| 491 | 495 | </pre> |
| 492 | 496 | |
| 493 | -The <i>repository-filename</i> can be omitted when these commands | |
| 494 | -are run from within an open check-out, which is a particularly useful | |
| 495 | -shortcut with the <b>fossil ui</b> command. | |
| 496 | - | |
| 497 | -The <b>ui</b> command is intended for accessing the web user interface | |
| 498 | -from a local desktop. (We sometimes call this mode "Fossil UI.") | |
| 499 | -The <b>ui</b> command differs from the | |
| 500 | -<b>server</b> command by binding to the loopback IP | |
| 501 | -address only (thus making the web UI visible only on the | |
| 502 | -local machine) and by automatically starting your default web browser, | |
| 503 | -pointing it at the running UI | |
| 504 | -server. The localhost restriction exists because it also gives anyone | |
| 505 | -who can access the resulting web UI full control over the | |
| 506 | -repository. (This is the [./caps/admin-v-setup.md#apsu | all-powerful | |
| 507 | -Setup capabliity].) | |
| 508 | - | |
| 509 | -For cross-machine collaboration, use the <b>server</b> command instead, | |
| 510 | -which binds on all IP addresses, does not try to start a web browser, | |
| 511 | -and enforces [./caps/ | Fossil's role-based access control system]. | |
| 512 | - | |
| 513 | -Servers are also easily configured as: | |
| 497 | +Just as with <b>fossil ui</b>, you may omit the | |
| 498 | +<i>repository-filename</i> parameter when running this from within an open | |
| 499 | +check-out. | |
| 500 | + | |
| 501 | +<i>Unlike</i> <b>fossil ui</b> mode, Fossil binds to all network | |
| 502 | +interfaces by default in this mode, and it enforces the configured | |
| 503 | +[./caps/ | role-based access controls]. Further, because it is meant to | |
| 504 | +provide external web service, it doesn't try to launch a local web | |
| 505 | +browser pointing to a "Fossil UI" presentation; external visitors see | |
| 506 | +your repository's configured home page instead. | |
| 507 | + | |
| 508 | +To serve varying needs, there are additional ways to serve a Fossil repo | |
| 509 | +to external users: | |
| 514 | 510 | |
| 515 | 511 | <ul> |
| 512 | +<li>[./server/any/cgi.md|CGI], as used by Fossil's [./selfhost.wiki | | |
| 513 | + self-hosting repositories] | |
| 514 | +<li>[./server/any/scgi.md|SCGI] | |
| 516 | 515 | <li>[./server/any/inetd.md|inetd] |
| 517 | 516 | <li>[./server/debian/service.md|systemd] |
| 518 | -<li>[./server/any/cgi.md|CGI] | |
| 519 | -<li>[./server/any/scgi.md|SCGI] | |
| 520 | 517 | </ul> |
| 521 | 518 | |
| 522 | 519 | …along with [./server/#matrix | several other options]. |
| 523 | 520 | |
| 524 | -The [./selfhost.wiki | self-hosting fossil repositories] use | |
| 525 | -CGI. | |
| 526 | - | |
| 527 | -You might <i>need</i> to set up a server, whether you know it yet or | |
| 528 | -not. See the [./server/whyuseaserver.wiki | Benefits of a Fossil Server] | |
| 529 | -article for details. | |
| 521 | +We recommend that you read the [./server/whyuseaserver.wiki | Benefits | |
| 522 | +of a Fossil Server] article, because you might <i>need</i> to do this | |
| 523 | +and not yet know it. | |
| 530 | 524 | |
| 531 | 525 | <h2 id="proxy">HTTP Proxies</h2> |
| 532 | 526 | |
| 533 | 527 | If you are behind a restrictive firewall that requires you to use |
| 534 | 528 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 535 | 529 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -322,34 +322,39 @@ | |
| 322 | |
| 323 | This will get you started on identifying checkins. The |
| 324 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 325 | how timestamps can also be used. |
| 326 | |
| 327 | <h2 id="config">Configuring Your Local Repository</h2> |
| 328 | |
| 329 | When you create a new repository, either by cloning an existing |
| 330 | project or create a new project of your own, you usually want to do some |
| 331 | local configuration. This is most easily accomplished using the web-server |
| 332 | that is built into Fossil, like so: |
| 333 | |
| 334 | <pre> |
| 335 | <b>fossil ui</b> <i>repository-filename</i> |
| 336 | </pre> |
| 337 | |
| 338 | You can shorten that to just [/help/ui | <b>fossil ui</b>] |
| 339 | if you are inside a checked-out local tree. |
| 340 | |
| 341 | After the internal web server starts, Fossil automatically launches your |
| 342 | default web browser, pointed at itself. You may override that default so: |
| 343 | |
| 344 | <pre> |
| 345 | <b>fossil setting web-browser</b> <i>path-to-web-browser</i> |
| 346 | </pre> |
| 347 | |
| 348 | Fossil binds this web server to the IP loopback address (127.0.0.1) |
| 349 | which it treats specially when launched this way, bypassing all user |
| 350 | controls. Why is that a good idea, you ask? Because it is a safe |
| 351 | presumption that only someone with direct file access to the repository |
| 352 | database file could be using the resulting web interface. Anyone who can |
| 353 | modify the repo DB directly could give themselves any and all access |
| 354 | with a SQL query, or even by direct file manipulation; no amount of |
| 355 | access control matters to such a user. |
| @@ -480,55 +485,44 @@ | |
| 480 | level of undo/redo. |
| 481 | |
| 482 | |
| 483 | <h2 id="server">Setting Up A Server</h2> |
| 484 | |
| 485 | Fossil can act as a stand-alone web server using one of these |
| 486 | commands: |
| 487 | |
| 488 | <pre> |
| 489 | <b>[/help/server | fossil server]</b> <i>repository-filename</i> |
| 490 | <b>[/help/ui | fossil ui]</b> <i>repository-filename</i> |
| 491 | </pre> |
| 492 | |
| 493 | The <i>repository-filename</i> can be omitted when these commands |
| 494 | are run from within an open check-out, which is a particularly useful |
| 495 | shortcut with the <b>fossil ui</b> command. |
| 496 | |
| 497 | The <b>ui</b> command is intended for accessing the web user interface |
| 498 | from a local desktop. (We sometimes call this mode "Fossil UI.") |
| 499 | The <b>ui</b> command differs from the |
| 500 | <b>server</b> command by binding to the loopback IP |
| 501 | address only (thus making the web UI visible only on the |
| 502 | local machine) and by automatically starting your default web browser, |
| 503 | pointing it at the running UI |
| 504 | server. The localhost restriction exists because it also gives anyone |
| 505 | who can access the resulting web UI full control over the |
| 506 | repository. (This is the [./caps/admin-v-setup.md#apsu | all-powerful |
| 507 | Setup capabliity].) |
| 508 | |
| 509 | For cross-machine collaboration, use the <b>server</b> command instead, |
| 510 | which binds on all IP addresses, does not try to start a web browser, |
| 511 | and enforces [./caps/ | Fossil's role-based access control system]. |
| 512 | |
| 513 | Servers are also easily configured as: |
| 514 | |
| 515 | <ul> |
| 516 | <li>[./server/any/inetd.md|inetd] |
| 517 | <li>[./server/debian/service.md|systemd] |
| 518 | <li>[./server/any/cgi.md|CGI] |
| 519 | <li>[./server/any/scgi.md|SCGI] |
| 520 | </ul> |
| 521 | |
| 522 | …along with [./server/#matrix | several other options]. |
| 523 | |
| 524 | The [./selfhost.wiki | self-hosting fossil repositories] use |
| 525 | CGI. |
| 526 | |
| 527 | You might <i>need</i> to set up a server, whether you know it yet or |
| 528 | not. See the [./server/whyuseaserver.wiki | Benefits of a Fossil Server] |
| 529 | article for details. |
| 530 | |
| 531 | <h2 id="proxy">HTTP Proxies</h2> |
| 532 | |
| 533 | If you are behind a restrictive firewall that requires you to use |
| 534 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 535 |
| --- www/quickstart.wiki | |
| +++ www/quickstart.wiki | |
| @@ -322,34 +322,39 @@ | |
| 322 | |
| 323 | This will get you started on identifying checkins. The |
| 324 | <a href="./checkin_names.wiki">Checkin Names document</a> is a complete reference, including |
| 325 | how timestamps can also be used. |
| 326 | |
| 327 | <h2 id="config">Accessing Your Local Repository's Web User Interface</h2> |
| 328 | |
| 329 | After you create a new repository, you usually want to do some local |
| 330 | configuration. This is most easily accomplished by firing up the Fossil |
| 331 | UI: |
| 332 | |
| 333 | <pre> |
| 334 | <b>fossil ui</b> <i>repository-filename</i> |
| 335 | </pre> |
| 336 | |
| 337 | You can shorten that to just [/help/ui | <b>fossil ui</b>] |
| 338 | if you are inside a checked-out local tree. |
| 339 | |
| 340 | This command starts an internal web server, after which Fossil |
| 341 | automatically launches your default browser, pointed at itself, |
| 342 | presenting a special view of the repository, its web user interface. |
| 343 | |
| 344 | You may override Fossil's logic for selecting the default browser so: |
| 345 | |
| 346 | <pre> |
| 347 | <b>fossil setting web-browser</b> <i>path-to-web-browser</i> |
| 348 | </pre> |
| 349 | |
| 350 | When launched this way, Fossil binds its internal web server to the IP |
| 351 | loopback address, 127.0.0.1, which it treats specially, bypassing all |
| 352 | user controls, effectively giving visitors the |
| 353 | [./caps/admin-v-setup.md#apsu | all-powerful Setup capabliity]. |
| 354 | |
| 355 | Why is that a good idea, you ask? Because it is a safe |
| 356 | presumption that only someone with direct file access to the repository |
| 357 | database file could be using the resulting web interface. Anyone who can |
| 358 | modify the repo DB directly could give themselves any and all access |
| 359 | with a SQL query, or even by direct file manipulation; no amount of |
| 360 | access control matters to such a user. |
| @@ -480,55 +485,44 @@ | |
| 485 | level of undo/redo. |
| 486 | |
| 487 | |
| 488 | <h2 id="server">Setting Up A Server</h2> |
| 489 | |
| 490 | In addition to the inward-facing <b>fossil ui</b> mode covered [#config |
| 491 | | above], Fossil can also act as an outward-facing web server: |
| 492 | |
| 493 | <pre> |
| 494 | <b>[/help/server | fossil server]</b> <i>repository-filename</i> |
| 495 | </pre> |
| 496 | |
| 497 | Just as with <b>fossil ui</b>, you may omit the |
| 498 | <i>repository-filename</i> parameter when running this from within an open |
| 499 | check-out. |
| 500 | |
| 501 | <i>Unlike</i> <b>fossil ui</b> mode, Fossil binds to all network |
| 502 | interfaces by default in this mode, and it enforces the configured |
| 503 | [./caps/ | role-based access controls]. Further, because it is meant to |
| 504 | provide external web service, it doesn't try to launch a local web |
| 505 | browser pointing to a "Fossil UI" presentation; external visitors see |
| 506 | your repository's configured home page instead. |
| 507 | |
| 508 | To serve varying needs, there are additional ways to serve a Fossil repo |
| 509 | to external users: |
| 510 | |
| 511 | <ul> |
| 512 | <li>[./server/any/cgi.md|CGI], as used by Fossil's [./selfhost.wiki | |
| 513 | self-hosting repositories] |
| 514 | <li>[./server/any/scgi.md|SCGI] |
| 515 | <li>[./server/any/inetd.md|inetd] |
| 516 | <li>[./server/debian/service.md|systemd] |
| 517 | </ul> |
| 518 | |
| 519 | …along with [./server/#matrix | several other options]. |
| 520 | |
| 521 | We recommend that you read the [./server/whyuseaserver.wiki | Benefits |
| 522 | of a Fossil Server] article, because you might <i>need</i> to do this |
| 523 | and not yet know it. |
| 524 | |
| 525 | <h2 id="proxy">HTTP Proxies</h2> |
| 526 | |
| 527 | If you are behind a restrictive firewall that requires you to use |
| 528 | an HTTP proxy to reach the internet, then you can configure the proxy |
| 529 |