CLIF makes use of a stack of components that are configured for working together.
These are described below. They are all optional and they only need be installed
if the specific functionality is needed.




Gitolite
-------------------------------------------------------------------------------

This component is not required if CLIF is being installed as a personal instance
for a single user. If that's the case, this component can be ignored.
For muli-user instances tha require fine-grained access control, this component
is required and should be installed.

Follow the instructions at https://gitolite.com/gitolite/fool_proof_setup.html for
installing Gitolite. As a quick reference this is how to install Gitolite for user
"git":

    su - git
    git clone https://github.com/sitaramc/gitolite
    gitolite/install -to $HOME/bin
    $HOME/bin/gitolite setup -pk <admin_key>.pub

Gitolite does not do authentication, it only does authorization. The name of the
logged in user is provided to Gitolite by SSH or by the web server, after authentication.
In order to allow anonymous HTTP clones, the web UI automatically sets a generic
username value of "anonymous". We need to let Gitolite know what the unauthenticated
user is going to be named. To do this, add the following line in ~/.gitolite.rc
in the section "rc variables used by various features". This is explained at
https://gitolite.com/gitolite/http.html#allowing-unauthenticated-access

    HTTP_ANON_USER => 'anonymous',

Also enable non-core commands that are useful to us. These commands are shipped
with Gitolite but disabled by default. A list of available commands can be found
at https://gitolite.com/gitolite/list-non-core.html

    'ENABLE' => [
        ... existing commands

        # Allow to change HEAD reference (default branch) like this:
        # ssh git@host symbolic-ref <repo> HEAD refs/heads/<name>
        'symbolic-ref',
    ]

Administration is done by cloning the gitolite-admin repository.
For adding new users, add their public key to gitolite-admin/keydir/<username>.pub
and then create a namespace in gitolite-admin/conf/gitolite.conf so they can create
new repositories:

    repo <username>/..*
        C   =   <username>
        RW+ =   <username>
        R   =   @all




Web UI
-------------------------------------------------------------------------------

This is a read-only web interface for displaying Git repositories and mailing lists.

1. Clone the CLIF repository
    su - git
    git clone https://clif.peers.community/zplus/clif.git /home/git/clif

2. Install the Python dependencies
    cd /home/git/clif
    python3 -m venv venv
    venv/bin/pip install -r requirements.txt

3. Configure it
web.py contains a list of options at the top of the file. Configure these as needed.
The most important one is REPOSITORIES_ROOT which specifies where the program should
scan for repositories. If Gitolite is installed this should be the path to Gitolite's
"repositories" folder, otherwise any other folder containing Git repositories.

4. Install a SystemD service for controlling the UI service:
    cp web.service /etc/systemd/system/clif-web.service
    systemctl daemon-reload
    systemctl enable clif-web
    systemctl start clif-web




HTTP reverse proxy + Let's Encrypt certificate
-------------------------------------------------------------------------------

This section shows how to configure lighttpd as a reverse proxy for the web UI,
with also a TLS certificate.

    apt-get install certbot
    certbot certonly --webroot -w /var/www/html -d example.org

The cert is created in /etc/letsencrypt/live/example.org/
Lighttpd requires the certificate and private key to be in a single file:

    cat privkey.pem cert.pem > privkey+cert.pem

Add to lighttpd configuration:

    $ vim /etc/lighttpd/lighttpd.conf

    server.modules += (
        "mod_fastcgi",
        "mod_proxy",
    )

    # Redirect all HTTP requests to HTTPS by default, except /.well-known which is
    # used by Let's Encrypt for renewing certificates.
    $HTTP["scheme"] == "http" {
        $HTTP["url"] !~ "^/.well-known/(.*)" {
            url.redirect = ("" => "https://${url.authority}${url.path}${qsa}")
            url.redirect-code = 308
        }
    }

    $HTTP["host"] == "example.org" {
        $SERVER["socket"] == ":443" {
            ssl.engine = "enable"
            ssl.pemfile = "/etc/letsencrypt/live/example.org/privkey+cert.pem"
            ssl.ca-file = "/etc/letsencrypt/live/example.org/chain.pem"

            proxy.server = (
                "" => (
                    ( "host" => "127.0.0.1", "port" => 5000 )
                )
            )
            # server.document-root = "/var/www/html"
            # server.errorlog = "/"
            # accesslog.filename = "/"
        }
    }

Let's Encrypt certificates expire every 90 days, so a cron job needs to be set up
that will generate a new privkey+cert.pem file and reload lighttpd.

    $ vim /etc/cron.weekly/clif-letsencrypt
    $ chmod +x /etc/cron.weekly/clif-letsencrypt

    # Content of "clif-letsencrypt"
    certbot renew --webroot -w /var/www/html
    cd /etc/letsencrypt/live/example.org
    cat privkey.pem cert.pem > privkey+cert.pem
    systemctl restart lighttpd




Mailing Lists
-------------------------------------------------------------------------------

1. There are a couple of settings at the top of emails.py. Change them as needed.

2. Add the following to /etc/postfix/main.cf. This will forward all emails to the
system user "git"

    luser_relay = git
    local_recipient_maps =

3. Create the file /home/git/.forward with the content:

    |/home/git/clif/emails.py

This is a sendmail file (also used by postfix) for deciding how incoming messages
shall be delivered to the the system user. For our purposes, we instruct postfix
to pipe all the emails for user "git" to our script.
Make sure the script is executable.

TODO Add documentation for SPF, DKIM, DMARC, SRS, ARC (and more..?)