Fossil SCM
Additional interlinking and clarification of CGI documentation.
Commit
43fb402bfd374f71bf2d3a13c59435b67e8cc86f14315ce04d4fda234abe4677
Parent
9601b6cfc747066…
4 files changed
+21
-4
+1
-2
+4
-2
+1
-1
+21
-4
| --- www/aboutcgi.wiki | ||
| +++ www/aboutcgi.wiki | ||
| @@ -1,12 +1,16 @@ | ||
| 1 | 1 | <title>How CGI Works In Fossil</title> |
| 2 | 2 | <h2>Introduction</h2><blockquote> |
| 3 | 3 | <p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 4 | 4 | generating dynamic web content. This article gives a quick background on how |
| 5 | 5 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | -<p>This is a "how it works" guide. If you just want to set up Fossil | |
| 7 | -as a CGI server, see the [./server/ | Fossil Server Setup] page. | |
| 6 | +<p>This is a "how it works" guide. This document provides background | |
| 7 | +information on the CGI protocol so that you can better understand what | |
| 8 | +is going on behind the scenes. If you just want to set up Fossil | |
| 9 | +as a CGI server, see the [./server/ | Fossil Server Setup] page. Or | |
| 10 | +if you want to development CGI-based extensions to Fossil, see | |
| 11 | +the [./serverext.wiki|CGI Server Extensions] page. | |
| 8 | 12 | </blockquote> |
| 9 | 13 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 10 | 14 | <p> |
| 11 | 15 | An HTTP request is a block of text that is sent by a client application |
| 12 | 16 | (usually a web browser) and arrives at the web server over a network |
| @@ -14,20 +18,20 @@ | ||
| 14 | 18 | being requested. The URL in the HTTP request is typically the same URL |
| 15 | 19 | that appears in the URL bar at the top of the web browser that is making |
| 16 | 20 | the request. The URL might contain a "?" character followed |
| 17 | 21 | query parameters. The HTTP will usually also contain other information |
| 18 | 22 | such as the name of the application that made the request, whether or |
| 19 | -not the requesting application can except a compressed reply, POST | |
| 23 | +not the requesting application can accept a compressed reply, POST | |
| 20 | 24 | parameters from forms, and so forth. |
| 21 | 25 | <p> |
| 22 | 26 | The job of the web server is to interpret the HTTP request and formulate |
| 23 | 27 | an appropriate reply. |
| 24 | 28 | The web server is free to interpret the HTTP request in any way it wants. |
| 25 | 29 | But most web servers follow a similar pattern, described below. |
| 26 | 30 | (Note: details may vary from one web server to another.) |
| 27 | 31 | <p> |
| 28 | -Suppose the URL in the HTTP request looks like this: | |
| 32 | +Suppose the filename component of the URL in the HTTP request looks like this: | |
| 29 | 33 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 30 | 34 | Most web servers will search their content area for files that match |
| 31 | 35 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 32 | 36 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 33 | 37 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| @@ -180,10 +184,23 @@ | ||
| 180 | 184 | a repository. The PATH_INFO is shortened by removing |
| 181 | 185 | "subdir/three/" leaving it at just "timeline". |
| 182 | 186 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 183 | 187 | requested is "timeline". |
| 184 | 188 | </ol> |
| 189 | +<a name="cgivar"></a> | |
| 190 | +The web server sets many environment variables in step 2 in addition | |
| 191 | +to just PATH_INFO. The following diagram shows a few of these variables | |
| 192 | +and their relationship to the request URL: | |
| 193 | +<pre> | |
| 194 | + REQUEST_URI | |
| 195 | + ______________|___________________ | |
| 196 | + / \ | |
| 197 | + http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1 | |
| 198 | + \_________/\____________/\____________________/ \______/ | |
| 199 | + | | | | | |
| 200 | + HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING | |
| 201 | +</pre> | |
| 185 | 202 | </blockquote> |
| 186 | 203 | <h2>Additional CGI Script Options</h2> |
| 187 | 204 | <blockquote> |
| 188 | 205 | <p> |
| 189 | 206 | The CGI script can have additional options used to fine-tune |
| 190 | 207 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,12 +1,16 @@ | |
| 1 | <title>How CGI Works In Fossil</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | <p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 4 | generating dynamic web content. This article gives a quick background on how |
| 5 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | <p>This is a "how it works" guide. If you just want to set up Fossil |
| 7 | as a CGI server, see the [./server/ | Fossil Server Setup] page. |
| 8 | </blockquote> |
| 9 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 10 | <p> |
| 11 | An HTTP request is a block of text that is sent by a client application |
| 12 | (usually a web browser) and arrives at the web server over a network |
| @@ -14,20 +18,20 @@ | |
| 14 | being requested. The URL in the HTTP request is typically the same URL |
| 15 | that appears in the URL bar at the top of the web browser that is making |
| 16 | the request. The URL might contain a "?" character followed |
| 17 | query parameters. The HTTP will usually also contain other information |
| 18 | such as the name of the application that made the request, whether or |
| 19 | not the requesting application can except a compressed reply, POST |
| 20 | parameters from forms, and so forth. |
| 21 | <p> |
| 22 | The job of the web server is to interpret the HTTP request and formulate |
| 23 | an appropriate reply. |
| 24 | The web server is free to interpret the HTTP request in any way it wants. |
| 25 | But most web servers follow a similar pattern, described below. |
| 26 | (Note: details may vary from one web server to another.) |
| 27 | <p> |
| 28 | Suppose the URL in the HTTP request looks like this: |
| 29 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 30 | Most web servers will search their content area for files that match |
| 31 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 32 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 33 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| @@ -180,10 +184,23 @@ | |
| 180 | a repository. The PATH_INFO is shortened by removing |
| 181 | "subdir/three/" leaving it at just "timeline". |
| 182 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 183 | requested is "timeline". |
| 184 | </ol> |
| 185 | </blockquote> |
| 186 | <h2>Additional CGI Script Options</h2> |
| 187 | <blockquote> |
| 188 | <p> |
| 189 | The CGI script can have additional options used to fine-tune |
| 190 |
| --- www/aboutcgi.wiki | |
| +++ www/aboutcgi.wiki | |
| @@ -1,12 +1,16 @@ | |
| 1 | <title>How CGI Works In Fossil</title> |
| 2 | <h2>Introduction</h2><blockquote> |
| 3 | <p>CGI or "Common Gateway Interface" is a venerable yet reliable technique for |
| 4 | generating dynamic web content. This article gives a quick background on how |
| 5 | CGI works and describes how Fossil can act as a CGI service. |
| 6 | <p>This is a "how it works" guide. This document provides background |
| 7 | information on the CGI protocol so that you can better understand what |
| 8 | is going on behind the scenes. If you just want to set up Fossil |
| 9 | as a CGI server, see the [./server/ | Fossil Server Setup] page. Or |
| 10 | if you want to development CGI-based extensions to Fossil, see |
| 11 | the [./serverext.wiki|CGI Server Extensions] page. |
| 12 | </blockquote> |
| 13 | <h2>A Quick Review Of CGI</h2><blockquote> |
| 14 | <p> |
| 15 | An HTTP request is a block of text that is sent by a client application |
| 16 | (usually a web browser) and arrives at the web server over a network |
| @@ -14,20 +18,20 @@ | |
| 18 | being requested. The URL in the HTTP request is typically the same URL |
| 19 | that appears in the URL bar at the top of the web browser that is making |
| 20 | the request. The URL might contain a "?" character followed |
| 21 | query parameters. The HTTP will usually also contain other information |
| 22 | such as the name of the application that made the request, whether or |
| 23 | not the requesting application can accept a compressed reply, POST |
| 24 | parameters from forms, and so forth. |
| 25 | <p> |
| 26 | The job of the web server is to interpret the HTTP request and formulate |
| 27 | an appropriate reply. |
| 28 | The web server is free to interpret the HTTP request in any way it wants. |
| 29 | But most web servers follow a similar pattern, described below. |
| 30 | (Note: details may vary from one web server to another.) |
| 31 | <p> |
| 32 | Suppose the filename component of the URL in the HTTP request looks like this: |
| 33 | <blockquote><b>/one/two/timeline/four</b></blockquote> |
| 34 | Most web servers will search their content area for files that match |
| 35 | some prefix of the URL. The search starts with <b>/one</b>, then goes to |
| 36 | <b>/one/two</b>, then <b>/one/two/timeline</b>, and finally |
| 37 | <b>/one/two/timeline/four</b> is checked. The search stops at the first |
| @@ -180,10 +184,23 @@ | |
| 184 | a repository. The PATH_INFO is shortened by removing |
| 185 | "subdir/three/" leaving it at just "timeline". |
| 186 | <li> Fossil looks at the rest of PATH_INFO to see that the webpage |
| 187 | requested is "timeline". |
| 188 | </ol> |
| 189 | <a name="cgivar"></a> |
| 190 | The web server sets many environment variables in step 2 in addition |
| 191 | to just PATH_INFO. The following diagram shows a few of these variables |
| 192 | and their relationship to the request URL: |
| 193 | <pre> |
| 194 | REQUEST_URI |
| 195 | ______________|___________________ |
| 196 | / \ |
| 197 | http://example.com/cgis/example2/subdir/three/timeline?c=55d7e1 |
| 198 | \_________/\____________/\____________________/ \______/ |
| 199 | | | | | |
| 200 | HTTP_HOST SCRIPT_NAME PATH_INFO QUERY_STRING |
| 201 | </pre> |
| 202 | </blockquote> |
| 203 | <h2>Additional CGI Script Options</h2> |
| 204 | <blockquote> |
| 205 | <p> |
| 206 | The CGI script can have additional options used to fine-tune |
| 207 |
+1
-2
| --- www/selfhost.wiki | ||
| +++ www/selfhost.wiki | ||
| @@ -5,11 +5,10 @@ | ||
| 5 | 5 | |
| 6 | 6 | 1. [https://www.fossil-scm.org/] |
| 7 | 7 | 2. [https://www2.fossil-scm.org/] |
| 8 | 8 | 3. [https://www3.fossil-scm.org/site.cgi] |
| 9 | 9 | |
| 10 | - | |
| 11 | 10 | The canonical repository is (1). Repositories (2) and (3) automatically |
| 12 | 11 | stay in synchronization with (1) via a |
| 13 | 12 | <a href="http://en.wikipedia.org/wiki/Cron">cron job</a> that invokes |
| 14 | 13 | "fossil sync" at regular intervals. |
| 15 | 14 | Repository (2) also publishes a |
| @@ -19,11 +18,11 @@ | ||
| 19 | 18 | All three servers support full read/write capabilities. |
| 20 | 19 | Changes (such as new tickets or wiki or check-ins) can be implemented |
| 21 | 20 | on any of the three servers and those changes automatically propagate to the |
| 22 | 21 | other two servers. |
| 23 | 22 | |
| 24 | -Server (1) runs as a CGI script on a | |
| 23 | +Server (1) runs as a [./aboutcgi.wiki|CGI script] on a | |
| 25 | 24 | <a href="http://www.linode.com/">Linode 8192</a> located in Dallas, TX |
| 26 | 25 | - on the same virtual machine that |
| 27 | 26 | hosts <a href="http://www.sqlite.org/">SQLite</a> and over a |
| 28 | 27 | dozen other smaller projects. This demonstrates that Fossil can run on |
| 29 | 28 | a low-power host processor. |
| 30 | 29 |
| --- www/selfhost.wiki | |
| +++ www/selfhost.wiki | |
| @@ -5,11 +5,10 @@ | |
| 5 | |
| 6 | 1. [https://www.fossil-scm.org/] |
| 7 | 2. [https://www2.fossil-scm.org/] |
| 8 | 3. [https://www3.fossil-scm.org/site.cgi] |
| 9 | |
| 10 | |
| 11 | The canonical repository is (1). Repositories (2) and (3) automatically |
| 12 | stay in synchronization with (1) via a |
| 13 | <a href="http://en.wikipedia.org/wiki/Cron">cron job</a> that invokes |
| 14 | "fossil sync" at regular intervals. |
| 15 | Repository (2) also publishes a |
| @@ -19,11 +18,11 @@ | |
| 19 | All three servers support full read/write capabilities. |
| 20 | Changes (such as new tickets or wiki or check-ins) can be implemented |
| 21 | on any of the three servers and those changes automatically propagate to the |
| 22 | other two servers. |
| 23 | |
| 24 | Server (1) runs as a CGI script on a |
| 25 | <a href="http://www.linode.com/">Linode 8192</a> located in Dallas, TX |
| 26 | - on the same virtual machine that |
| 27 | hosts <a href="http://www.sqlite.org/">SQLite</a> and over a |
| 28 | dozen other smaller projects. This demonstrates that Fossil can run on |
| 29 | a low-power host processor. |
| 30 |
| --- www/selfhost.wiki | |
| +++ www/selfhost.wiki | |
| @@ -5,11 +5,10 @@ | |
| 5 | |
| 6 | 1. [https://www.fossil-scm.org/] |
| 7 | 2. [https://www2.fossil-scm.org/] |
| 8 | 3. [https://www3.fossil-scm.org/site.cgi] |
| 9 | |
| 10 | The canonical repository is (1). Repositories (2) and (3) automatically |
| 11 | stay in synchronization with (1) via a |
| 12 | <a href="http://en.wikipedia.org/wiki/Cron">cron job</a> that invokes |
| 13 | "fossil sync" at regular intervals. |
| 14 | Repository (2) also publishes a |
| @@ -19,11 +18,11 @@ | |
| 18 | All three servers support full read/write capabilities. |
| 19 | Changes (such as new tickets or wiki or check-ins) can be implemented |
| 20 | on any of the three servers and those changes automatically propagate to the |
| 21 | other two servers. |
| 22 | |
| 23 | Server (1) runs as a [./aboutcgi.wiki|CGI script] on a |
| 24 | <a href="http://www.linode.com/">Linode 8192</a> located in Dallas, TX |
| 25 | - on the same virtual machine that |
| 26 | hosts <a href="http://www.sqlite.org/">SQLite</a> and over a |
| 27 | dozen other smaller projects. This demonstrates that Fossil can run on |
| 28 | a low-power host processor. |
| 29 |
+4
-2
| --- www/server/any/cgi.md | ||
| +++ www/server/any/cgi.md | ||
| @@ -1,11 +1,13 @@ | ||
| 1 | 1 | # Serving via CGI |
| 2 | 2 | |
| 3 | 3 | A Fossil server can be run from most ordinary web servers as a CGI |
| 4 | 4 | program. This feature allows Fossil to seamlessly integrate into a |
| 5 | -larger website. We use CGI for the [self-hosting Fossil repository web | |
| 6 | -site](../../selfhost.wiki). | |
| 5 | +larger website. The [self-hosting Fossil repository web | |
| 6 | +site](../../selfhost.wiki) is implemented using CGI. See the | |
| 7 | +[How CGI Works](../../aboutcgi.wiki) page for background information | |
| 8 | +on the CGI protocol. | |
| 7 | 9 | |
| 8 | 10 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 9 | 11 | CGI directory of your web server with content like this: |
| 10 | 12 | |
| 11 | 13 | #!/usr/bin/fossil |
| 12 | 14 |
| --- www/server/any/cgi.md | |
| +++ www/server/any/cgi.md | |
| @@ -1,11 +1,13 @@ | |
| 1 | # Serving via CGI |
| 2 | |
| 3 | A Fossil server can be run from most ordinary web servers as a CGI |
| 4 | program. This feature allows Fossil to seamlessly integrate into a |
| 5 | larger website. We use CGI for the [self-hosting Fossil repository web |
| 6 | site](../../selfhost.wiki). |
| 7 | |
| 8 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 9 | CGI directory of your web server with content like this: |
| 10 | |
| 11 | #!/usr/bin/fossil |
| 12 |
| --- www/server/any/cgi.md | |
| +++ www/server/any/cgi.md | |
| @@ -1,11 +1,13 @@ | |
| 1 | # Serving via CGI |
| 2 | |
| 3 | A Fossil server can be run from most ordinary web servers as a CGI |
| 4 | program. This feature allows Fossil to seamlessly integrate into a |
| 5 | larger website. The [self-hosting Fossil repository web |
| 6 | site](../../selfhost.wiki) is implemented using CGI. See the |
| 7 | [How CGI Works](../../aboutcgi.wiki) page for background information |
| 8 | on the CGI protocol. |
| 9 | |
| 10 | To run Fossil as CGI, create a CGI script (here called "repo") in the |
| 11 | CGI directory of your web server with content like this: |
| 12 | |
| 13 | #!/usr/bin/fossil |
| 14 |
+1
-1
| --- www/serverext.wiki | ||
| +++ www/serverext.wiki | ||
| @@ -1,11 +1,11 @@ | ||
| 1 | 1 | <title>CGI Server Extensions</title> |
| 2 | 2 | |
| 3 | 3 | <h2>1.0 Introduction</h2> |
| 4 | 4 | |
| 5 | 5 | If you have a [./server/|Fossil server] for your project, |
| 6 | -you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface|CGI] | |
| 6 | +you can add [./aboutcgi.wiki|CGI] | |
| 7 | 7 | extensions to that server. These extensions work like |
| 8 | 8 | any other CGI program, except that they also have access to the Fossil |
| 9 | 9 | login information and can (optionally) leverage the "skins" of Fossil |
| 10 | 10 | so that they appear to be more tightly integrated into the project. |
| 11 | 11 | |
| 12 | 12 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -1,11 +1,11 @@ | |
| 1 | <title>CGI Server Extensions</title> |
| 2 | |
| 3 | <h2>1.0 Introduction</h2> |
| 4 | |
| 5 | If you have a [./server/|Fossil server] for your project, |
| 6 | you can add [https://en.wikipedia.org/wiki/Common_Gateway_Interface|CGI] |
| 7 | extensions to that server. These extensions work like |
| 8 | any other CGI program, except that they also have access to the Fossil |
| 9 | login information and can (optionally) leverage the "skins" of Fossil |
| 10 | so that they appear to be more tightly integrated into the project. |
| 11 | |
| 12 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -1,11 +1,11 @@ | |
| 1 | <title>CGI Server Extensions</title> |
| 2 | |
| 3 | <h2>1.0 Introduction</h2> |
| 4 | |
| 5 | If you have a [./server/|Fossil server] for your project, |
| 6 | you can add [./aboutcgi.wiki|CGI] |
| 7 | extensions to that server. These extensions work like |
| 8 | any other CGI program, except that they also have access to the Fossil |
| 9 | login information and can (optionally) leverage the "skins" of Fossil |
| 10 | so that they appear to be more tightly integrated into the project. |
| 11 | |
| 12 |