diff --git a/documentation/administrators b/documentation/administrators index 6d56364..50a60b7 100644 --- a/documentation/administrators +++ b/documentation/administrators @@ -1,14 +1,167 @@ -# Adding new users +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. -1. Clone gitolite-admin.git repository -2. Add user key into gitolite-admin/keydir/.pub -# Assign namespaces to users -1. Clone gitolite-admin.git repository -2. Add rule into gitolite-admin/conf/gitolite.conf - repo namespace/..* - C = username - RW+ = username +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 .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 HEAD refs/heads/ + 'symbolic-ref', + ] + +Administration is done by cloning the gitolite-admin repository. +For adding new users, add their public key to gitolite-admin/keydir/.pub +and then create a namespace in gitolite-admin/conf/gitolite.conf so they can create +new repositories: + + repo /..* + C = + RW+ = 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 + +The cert is created in /etc/letsencrypt/live// +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 HTTP to HTTPS + $HTTP["scheme"] == "http" { + url.redirect = ("" => "https://${url.authority}${url.path}${qsa}") + url.redirect-code = 308 + } + + $SERVER["socket"] == ":443" { + ssl.engine = "enable" + ssl.pemfile = "/etc/letsencrypt/live//privkey+cert.pem" + ssl.ca-file = "/etc/letsencrypt/live//chain.pem" + + $HTTP["host"] == "" { + proxy.server = ( + "" => ( + ( "host" => "127.0.0.1", "port" => 5000 ) + ) + ) + } + } + +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 + cd /etc/letsencrypt/live/ + cat privkey.pem cert.pem > privkey+cert.pem + service lighttpd restart + + + + +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..?) diff --git a/documentation/installation b/documentation/installation deleted file mode 100644 index 0fdaee7..0000000 --- a/documentation/installation +++ /dev/null @@ -1,134 +0,0 @@ -Gitolite -------------------------------------------------------------------------------- - -Follow instructions at https://gitolite.com/gitolite/fool_proof_setup.html - -TL;DR: - su - git - git clone https://github.com/sitaramc/gitolite - gitolite/install -to $HOME/bin - $HOME/bin/gitolite setup -pk .pub - -Gitolite does not do authentication, it only does authorization. The name of the -logged in user is provided as an environment variable. In order to allow anonymous -HTTP clones, ie. for allowing "git clone https://..." without any authentication, -the web app automatically sets a generic username value of "anonymous". We need -to let Gitolite know what the unauthenticated user is going to be called so that -it can check authorization. To do this, just add the following to ~/.gitolite.rc -in the section marked "rc variables used by various features". This is explained -at https://gitolite.com/gitolite/http.html#allowing-unauthenticated-access - - HTTP_ANON_USER => 'anonymous', - -Enable some non-core commands that are useful to us. This is done by editing ~/.gitolite.rc: - - 'ENABLE' => [ - ... existing commands - - # Allow to change HEAD reference (default branch) like this: - # ssh git@host symbolic-ref HEAD refs/heads/ - 'symbolic-ref', - ] - - - - -Web UI -------------------------------------------------------------------------------- - -The CLIF repository is assumed to having been cloned into /home/git/clif. - -1. There are a couple of settings at the top of web.py. Change them. - -2. Install the Python dependencies: - - cd /home/git/clif - python3 -m venv venv - venv/bin/pip install -r requirements.txt - -3. Install a SystemD service for controlling the UI: - - cp web.service /etc/systemd/system/clif-web.service - systemctl daemon-reload - systemctl enable clif-web - systemctl start clif-web - - - - -Mailing Lists -------------------------------------------------------------------------------- - -1. There are a couple of settings at the top of emails.py. Change them. - -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. - - - - -Let's Encrypt certificate -------------------------------------------------------------------------------- - - apt-get install certbot - certbot certonly --webroot -w /var/www/html -d your-domain.tld - -The cert is created in /etc/letsencrypt/live// - -Lighttpd requires the certificate and private key to be in a single file: - - cat privkey.pem cert.pem > privkey+cert.pem - -Configure lighttpd reverse proxy: - - vim /etc/lighttpd/lighttpd.conf - - server.modules += ( - "mod_fastcgi", - "mod_proxy", - ) - - $HTTP["scheme"] == "http" { - url.redirect = ("" => "https://${url.authority}${url.path}${qsa}") - url.redirect-code = 308 - } - - $SERVER["socket"] == ":443" { - ssl.engine = "enable" - ssl.pemfile = "/etc/letsencrypt/live//privkey+cert.pem" - ssl.ca-file = "/etc/letsencrypt/live//chain.pem" - - $HTTP["host"] == "" { - proxy.server = ( - "" => ( - ( "host" => "127.0.0.1", "port" => 5000 ) - ) - ) - # server.document-root = "/var/www/html" # Document Root - # server.errorlog = "/" - # accesslog.filename = "/" - } - } - -Let's Encrypt certificates expire every 90 days, so we need to setup a cron job -that will generate a new privkey+cert.pem file, and reload lighttpd too. - - vim /etc/cron.weekly/clif-letsencrypt - chmod +x /etc/cron.weekly/clif-letsencrypt - - certbot renew - cd /etc/letsencrypt/live/ - cat privkey.pem cert.pem > privkey+cert.pem - service lighttpd restart diff --git a/documentation/users b/documentation/users index 030d339..8ab79fd 100644 --- a/documentation/users +++ b/documentation/users @@ -1,11 +1,11 @@ -General usage +Users ------------------------------------------------------------------------------- -# List of available commands over SSH +# List commands available to the user over SSH ssh git@example.org help -# List of user repositories and access permissions +# List user repositories and access permissions ssh git@example.org info @@ -15,34 +15,35 @@ General usage Repositories ------------------------------------------------------------------------------- -# Cloning a repository anonymously +# Clone repository anonymously - git clone https://example.org/repository.git + git clone https://example.org/.git -# Cloning a repository as registered users +# Clone repository (for registered users) - git clone git@example.org:repository + git clone git@example.org: -# Creating a new repository -Either clone, or push to, a nonexistent repository. It will be initiated automatically -as long as the user has write permission. +# Create new repository - git clone git@example.org:repository - git push git@example.org:repository master +Either clone, or push to, a nonexistent path. A new repository will be initiated +automatically. + + git clone git@example.org: + git push git@example.org: # Set repository description - ssh git@example.org desc "" + ssh git@example.org desc -# Pushing to a repository +# Push to repository - git push git@example.org:repository.git + git push git@example.org: -# Change default branch by repoint HEAD to other branches +# Change default branch by repointing HEAD - ssh git@example.org symbolic-ref repository.git HEAD refs/heads/main + ssh git@example.org symbolic-ref HEAD refs/heads/ -# Delete repository (D command) +# Delete repository (with D command) ssh git@example.org D unlock ssh git@example.org D rm @@ -53,34 +54,38 @@ as long as the user has write permission. Mailing lists ------------------------------------------------------------------------------- -Mailing lists are where collaboration happens, and they are stored in repositories -too. - -# Create a new mailing list +# Create new mailing list Create a new repository with the suffix ".mlist": - git clone git@example.org:project.mlist + git clone git@example.org:.mlist + +CLIF will then begin accepting emails for @example.org and it will +store them inside the .mlist repository. + +# Subscribe to lists + +Send an email to the list address with the +subscribe suffix. -CLIF will then begin accepting emails for project@example.org and store them -inside the "project.mlist" repository. + From: You + To: +subscribe@example.org -# Subscribe to a list +# Unsubscribe from lists -Send an email to the list address with the +subscribe suffix. For example -username/reponame+subscribe@example.org +Send an email to the list address with the +unsubscribe suffix. -# Unsubscribe from a list + From: You + To: +unsubscribe@example.org -Send an email to the list address with the +unsubscribe suffix. For example -username/reponame+unsubscribe@example.org +# New thread -# New threads +Send a new email to any list address. -New threads are created simply by sending a new email to the list address. An account -is not required for starting new threads and participating in discussions. +# Join existing thread -# Join an existing thread +Send an email containing the "In-Reply-To: " header, where +is the ID of any previous message. -It is possible to join an existing thread by sending an email containing the header -"In-Reply-To: ", where is the ID value of any previous message. + From: You + To: @example.org + In-Reply-To: