Description

A set of scripts to manage several Fossil repositories via SSH.
Create/delete repositories on the server, create/delete CGI scripts to access them via web, setup/update local clones, etc.

Purpose

When using only one or two Fossil repositories on one single computer, with no intention to share access, this directory layout may be considered overkill.

This Fossil repository is called nest as it acts like a container for other repositories (opened with the --nested flag).

The repository basically contains the following files:

• README.nest.md (this file)
• The bin/ directory, containing fsetup and other script
• Files for the web

Prerequisites

A server with SSH access, a CGI-enabled folder, and a 'fossil' executable.

Quick start

• Download this repos, either as a tarball or as a zip file.
  Untar/unzip and 'cd' to the 'nest' directory.

• Alternatively, if Fossil is installed locally, the repos may be cloned and opened as:

  mkdir -p repos nest
  fossil clone https://kuu.se/fossil/nest.cgi repos/nest.fossil
  cd nest
  fossil open ../repos/nest.fossil
  

In the 'nest' directory, run:

    ./bin/fsetup                  # First time run, cfg creation
    ./bin/fsetup -n <new_repos>   # Create new repos on server, clone, and checkout locally
    ./bin/fsetup <existing_repos> # Clone existing repos and checkout locally

But you should really read the rest of this README before running fsetup...

Directory Layout - Local computer

This Fossil repository, called nest, works as a container for other nested (child) repositories.
It is an example of a directory layout when working with several Fossil repositories (related or not).
fsetup is a tool to setup such a layout, and to synchronize repositories between machines.

Figure 1: The directory layout

This directory layout may be useful when using a public web server to centralize the access to the repositories.
In my case, I use multiple Virtual Machines on multiple computers, which means I may have up to a dozen checkouts of a repository floating around.
With a central point (the public web server) for the repositories, it is easy to keep them all up to date.

Refer to the network topology and directory layout further down, to get big picture, including the web server role.

README

This README describes the network topology and the directory layout used for this and the nested (child) repositories.
The also describes the fsetup script, which is a tool to automatize the repository setup and directory layout creation.

Common files

• index.html
  For web access to all Fossil repositories on a public web server.
  This file is updated by findex (called by fsetup) to list all (visible, i.e. not hidden) repositories. On a local computer, to list all repositories in a browser, use the following command instead:

     fossil ui $HOME/fossil/repos/
  

• Images and stylesheets
  The README.nest.md and index.html links to files in the img/ and css/ folders.

  • Scripts
    Instead of creating my custom scripts directly in $HOME/bin/, I keep them here, in the nest/bin/ folder, which is symlinked to $HOME/.
    fsetup is one of these scripts.

The fsetup script

Refer to the network topology and directory layout further down to get the big picture of the steps for this script.

The fsetup script: prerequisites

1. SSH client executable
   The ssh client comes installed with most UNIX/Linux/Mac distributions.
   On MS Windows, the MSYS/MINGW/CYGWIN packet manager offers openssh as a package.
   On MS Windows without MSYS/MINGW/CYGWIN, plink may be used instead.
   

https://www.ssh.com/ssh/putty/putty-manuals/0.68/Chapter7.html

1. Public web server with SSH access
   Using this setup, the repositories are created on an web server with SSH access.
   Locally cloned repositories and checkouts are updated and committed using SSH.
   The web interface for each repository requires HTTP/HTTPS access.
   Many shared web hosting services offer these prerequisites.

2. Passwordless SSH connection using SSH keys
   To avoid interactive password authentication when running fsetup, a private/public SSH key is recommended.
   README.ssh-keys.md

3. Fossil executable (both on server and on local computer)
   The recommended way to keep the fossil executable up to date is to use the https://www.fossil-scm.org repository.
   Anyway, this is a chicken-and-an-egg problem. To clone the fossil repository for the first time, fossil is needed.
   The solution is to install fossil once, using one of the following ways:

   • source code (for shared web hosts etc. without root access)
   • packet manager (Linux/BSD)
   • download precompiled binary (Mac/Windows)
     

   Optionally, to keep fossil up to date, clone the repository sources:

   fossil clone https://www.fossil-scm.org
   

   For installation documentation and troubleshooting, please refer to https://www.fossil-scm.org.
   Additional documentation (may be outdated): README.nest.md

The fsetup script: a set of scripts

• fsetup main script

  • fcfg configuration
  • fcgi create CGI file for a repository
  • fclone clone a remote repository
  • fconnect test SSH connection to server
  • fenv detect environment (platform and mandatory executables)
  • fhide show/hide a repository (toggle web access)
  • fgroup group repositories into categories (only affects how they are displayed on the "landing page")
  • findex update index.cgi and doc/tip/index.html on the server
  • flist list of all repositories on the server

The fsetup script: execution steps

First time setup:

    ./fsetup                  # First time run, cfg creation

1. If the configuration file fcfg does not exist, fsetup creates fcfg in the current directory and exits.
   
2. Edit fcfg to fit your needs (mandatory configuration for SSH access, optionally change the directory names).
3. Run fsetup again, and the main directory structure is created, i.e.: mkdir -p $HOME/fossil/repos/ $HOME/fossil/nest/bin/
   If missing, the additional scripts are downloaded into $HOME/fossil/nest/bin/.
   Why download, and not clone, the scripts? Because so many other files (useful to me, but useless to fsetup) are included in this repositories.

Daily usage:

    ./fsetup -n <new_repos>   # Create new repos on server, clone, and checkout locally
    ./fsetup <existing_repos> # Clone existing repos and checkout locally

New repository:
Create a new repository on the server with the -n flag and a repository name (without the .fossil extension).
The server repository is locally cloned, and a local (empty) checkout is created in a subdirectory with the same name as the repository name.

Existing repository:
Clone the server repository unless it doesn't exist locally, and create/update a local checkout in a subdirectory with the same name.

The network topology and directory layout

Figure 2: The network topology and directory layout