Artifact 8e46971181ac2c7438e2614ae16ef6929dc777d8
Wiki page
[Cookbook]
by
michael on
2008-05-25 07:50:11.
D 2008-05-25T07:50:11
L Cookbook
U michael
W 7234
<h1>Fossil Cookbook</h1>
The <cite>Fossil</cite> Cookbook is a collection of task-oriented instructions for intermediate users who wish to do more than basic operations with their <cite>Fossil</cite> repositories. The [Tutorial|tutorial] is a more suitable place for newcomers trying to learn the basic concepts to go first before tackling these recipes.
<h2>Index</h2>
Server recipes:
* <a href="#CGI">Using <cite>Fossil</cite>'s Built-In CGI</a>
<h2><a name="CGI">Using <cite>Fossil</cite>'s Built-In CGI</a></h2>
<h3>Motivation</h3>
* You want to share a repository through your existing web infrastructure.
* You want to share more than one repository at the same time.
<h3>Problem</h3>
Unlike some other distributed SCMs, <cite>Fossil</cite> can only clone, push, pull and and otherwise interact through repositories over HTTP. This can be simply and easily managed through use of the <code>fossil server</code> and/or <code>fossil ui</code> commands, of course, but this is really only adequate for ad-hoc repository sharing. Consider, for example, sharing ten repositories. Using the built-in server would require you to open ten ports in your firewall to permit access. Any serious sharing will require something more robust and permanent.
<h3>Solution</h3>
<cite>Fossil</cite> supports three different ways to share repositories. For ad-hoc sharing <code>fossil server/ui</code> is more than adequate. For more robust solutions, however, the use of <cite>(x)inetd</cite> or CGI support is indicated.
Setting up fossil for CGI support is simple. (Setting up your web server for CGI support may or may not be simple, but it is out of scope of this recipe. Consult your web server/service provider's documentation for this.)
<h4>UNIX</h4>
1. Find your CGI scripts directory (if applicable). This is commonly something like <base>/cgi-bin/, but does not have to be.
2. Inside that directory build a script file which looks like this:<br><code><pre> #! /usr/bin/env fossil<br> repository: /full/path/to/repository/file.fsl</pre></code>
3. Ensure that the script file so generated is set executable for the CGI user account.
4. Ensure that every directory in the path leading to the repository is browseable (chmod +x) to the CGI user account.
5. Ensure that the repository file is readable <em>and</em> writable to the CGI user account.
The following <cite>bash</cite> script can be run from within the directory containing the <cite>Fossil</cite> repositories to be shared (and, of course, altered for your setup) to set some of the constraints above up automatically:
<nowiki><font face="monospace">
<font color="#a52a2a"> 1 </font><font color="#0000ff">#! /usr/bin/env bash</font><br>
<font color="#a52a2a"> 2 </font><font color="#008b8b">CGI_ROOT</font>=/usr/lib/fossil<br>
<font color="#a52a2a"> 3 </font><font color="#008b8b">REPOSITORY_OWNER</font>=michael<br>
<font color="#a52a2a"> 4 </font><font color="#008b8b">CGI_GROUP</font>=www-data<br>
<font color="#a52a2a"> 5 </font><font color="#a52a2a"><b>if</b></font> <font color="#a52a2a"><b>[</b></font> <font color="#6a5acd">`whoami`</font> <font color="#a52a2a"><b>=</b></font> <font color="#ff00ff">'root'</font> <font color="#a52a2a"><b>]</b></font><br>
<font color="#a52a2a"> 6 </font><font color="#a52a2a"><b>then</b></font><br>
<font color="#a52a2a"> 7 </font> <font color="#a52a2a"><b>for</b></font> repository <font color="#a52a2a"><b>in</b></font> *.fsl<br>
<font color="#a52a2a"> 8 </font> <font color="#a52a2a"><b>do</b></font><br>
<font color="#a52a2a"> 9 </font> <font color="#008b8b">SOURCE</font>=<font color="#6a5acd">`</font><font color="#a52a2a"><b>pwd</b></font><font color="#6a5acd">`</font>/<font color="#a020f0">$repository</font><br>
<font color="#a52a2a">10 </font> <font color="#008b8b">DESTINATION</font>=<font color="#a020f0">$CGI_ROOT</font>/<font color="#a020f0">${</font><font color="#a020f0">repository</font><font color="#a52a2a"><b>%</b></font>.fsl<font color="#a020f0">}</font><br>
<font color="#a52a2a">11 </font> <font color="#a52a2a"><b>echo</b></font><font color="#ff00ff"> </font><font color="#a52a2a"><b>"</b></font><font color="#ff00ff">#! /usr/bin/env fossil</font><font color="#a52a2a"><b>"</b></font><font color="#ff00ff"> </font><font color="#a52a2a"><b>></b></font> <font color="#a020f0">$DESTINATION</font><br>
<font color="#a52a2a">12 </font> <font color="#a52a2a"><b>echo</b></font><font color="#ff00ff"> </font><font color="#a52a2a"><b>"</b></font><font color="#ff00ff">repository: </font><font color="#a020f0">$SOURCE</font><font color="#a52a2a"><b>"</b></font><font color="#ff00ff"> </font><font color="#a52a2a"><b>>></b></font> <font color="#a020f0">$DESTINATION</font><br>
<font color="#a52a2a">13 </font> chown <font color="#a020f0">$REPOSITORY_OWNER</font>:<font color="#a020f0">$CGI_GROUP</font> <font color="#a020f0">$SOURCE</font><br>
<font color="#a52a2a">14 </font> <font color="#a52a2a"><b>chmod</b></font> <font color="#ff00ff">664</font> <font color="#a020f0">$SOURCE</font><br>
<font color="#a52a2a">15 </font> chown root:root <font color="#a020f0">$DESTINATION</font><br>
<font color="#a52a2a">16 </font> <font color="#a52a2a"><b>chmod</b></font> <font color="#ff00ff">755</font> <font color="#a020f0">$DESTINATION</font><br>
<font color="#a52a2a">17 </font> <font color="#a52a2a"><b>done</b></font><br>
<font color="#a52a2a">18 </font><font color="#a52a2a"><b>else</b></font><br>
<font color="#a52a2a">19 </font> sudo <font color="#a020f0">$0</font> <font color="#a020f0">$*</font><br>
<font color="#a52a2a">20 </font><font color="#a52a2a"><b>fi</b></font><br>
</font></nowiki>
<h4>Windows</h4>
<i>Someone with access to a Windows machine complete with web server, etc. needs to write this portion. The CGI script is the same, but none of the other instructions make sense.</i>
<h3>Discussion</h3>
Using the CGI server is the best solution combining an existing web infrastructure and the sharing of many <cite>Fossil</cite> repositories. Unlike the ad-hoc solution which requires, in effect, a separate port for each simultaneously-shared repository, and which requires several instances of fossil running -- one for each shared repository -- the CGI approach uses URLs to distinguish between repositories and only (briefly) runs a copy of fossil when the repository is actually accessed.
Sharing repositories with CGI is really only worth the effort if more than one repository is being shared, however. With only one being shared, <code>fossil server</code> is likely more than adequate or the use of (x)inetd may be indicated. If, however, there is already an existing web infrastructure in place, CGI still may be preferred if only for consistency and maintainability of the system as a whole.
Z 298bbdedb6994bfe265c341c55c094b9