begriffs open source - repo-ui/blob - README.md

   1 ### Steps to self-host gitweb on openbsd
   2
   3 Build a simple web interface for your git repos using mostly built-in
   4 functionality of OpenBSD and git.
   5
   6 **Note:** I reconstructed these steps from memory after the fact. If any step
   7 fails for you as written, please email me so we can fix it.
   8
   9 #### git and its user
  10
  11 All repos will have public read-only git access. We'll also create a git user
  12 for write access over SSH.
  13
  14 ```sh
  15 # software deps not in base system (pandoc to render readmes)
  16 pkg_add git pandoc
  17
  18 useradd -m -s $(which git-shell) git
  19
  20 cat <<EOF >> /etc/ssh/sshd_config
  21 Match User git
  22         AllowAgentForwarding no
  23         AllowTcpForwarding no
  24         X11Forwarding no
  25         PermitTTY no
  26 EOF
  27
  28 # for cleaner read-write git urls
  29 ln -s /var/www/git /home/git/repo
  30 ```
  31
  32 #### chroot gitweb deps
  33
  34 The OpenBSD base system contains httpd and slowcgi which we'll use to run
  35 gitweb. By default CGI scripts have a chroot of `/var/www`, so any programs
  36 and shared libraries required by gitweb need to be copied there.
  37
  38 ```sh
  39 # home directory for projects
  40 install -g daemon -o git -d /var/www/git
  41
  42 # helper scripts from cozy forge
  43 ftp -o - https://dev.begriffs.com/repo-ui/snapshot/main.tar.gz | tar zxf -
  44 cd repo-ui-main-*
  45
  46 # copy required binaries and shared libs to chroot
  47 BINS="
  48 /usr/local/bin/git
  49 /usr/local/libexec/git/git-archive
  50 /usr/bin/perl
  51 "
  52
  53 for path in $BINS; do
  54     ./imprison "$path" /var/www
  55 done
  56
  57 # also copy system perl modules
  58 ./imprison-perl-modules /var/www
  59
  60 # the cgi program
  61 cp /usr/local/share/gitweb/gitweb.cgi /var/www/cgi-bin
  62
  63 # gitweb also needs a chrooted /dev/null
  64 mkdir /var/www/dev
  65 mknod /var/www/dev/null c 2 2 root:daemon
  66 chmod 0666 /var/www/dev/null
  67
  68 # git hook our repos will use
  69 install -D post-update /var/www/bin/post-update
  70 ```
  71
  72 #### generate tls certs
  73
  74 The OpenBSD base system contains acme-client(1) to retrieve https certs from
  75 Let's Encrypt. There is plenty of documentation online for this step. Try Roman
  76 Zolotarev's [guide](https://romanzolotarev.com/openbsd/acme-client.html).
  77
  78 When finished with this step, you'll have public and private keys in a
  79 subdirectory of `/etc/ssl`, and an `/etc/httpd.conf` file for your domain.
  80 You'll also have a cron job configured to renew your certificate.
  81
  82 #### configure httpd and gitweb
  83
  84 **Note:** the provided configuration files need customization for your domain
  85 name and the directories you used for your certs.
  86
  87 ```sh
  88 # default gitweb css and lightweight js
  89 cp -R /usr/local/share/gitweb/static /var/www
  90
  91 # back up your httpd config
  92 cp /etc/httpd.conf /tmp/httpd.conf.bak
  93
  94 # install configuration for gitweb and slowcgi
  95 cp httpd.conf /etc
  96
  97 # edit httpd.conf to customize for your domain
  98 # (consulting your backup as needed)
  99 vi /etc/httpd.conf
 100
 101 # gitweb configuration
 102 install -D gitweb.conf /var/www/conf/gitweb.conf
 103
 104 # update the domain name in the conf
 105 vi /var/www/conf/gitweb.conf
 106
 107 # add a message to your forge homepage
 108 cat <<EOF > /var/www/conf/projects_list_head.html
 109 <p>Introductory content for your projects list</p>
 110 EOF
 111
 112 # go time
 113 rcctl restart httpd
 114 ```
 115
 116 #### make a repo
 117
 118 All projects are stored as bare repos under `/var/www/git`. This directory is
 119 within the slowcgi chroot, unlike someplace like `/home/git`.
 120
 121 The category and description of each repo as displayed by gitweb are stored in
 122 plain text files within the bare repo (as part of git's database, not as
 123 versioned source code). Additionally, each repo needs a `post-update` hook to
 124 call `git update-server-info` whenever new code is pushed. We're using httpd to
 125 serve repos over "dumb https" rather than using a dedicated git protocol server.
 126 The `update-server-info` prepares files to make dumb http work.
 127
 128 Use a helper script to do all this:
 129
 130 ```sh
 131 # create the foo project, in category bar, with a description
 132 ./repo-new foo bar "a wonderful project"
 133 ```
 134
 135 The project will expose two git URLs:
 136
 137 * read-only: https://example.com/git/foo
 138 * read-write: git@example.com:repo/foo
 139
 140 **Mirrors**
 141
 142 To mirror dependencies on your own git server, use the helper script:
 143
 144 ```sh
 145 # for example, a hypothetical project foo on github
 146 ./repo-mirror foo https://github.com/user/foo.git
 147 ```
 148
 149 #### block large plagiarism models
 150
 151 Hosting your own projects off GitHub from the start avoids their being
 152 automatically used for training. However any public website will still be
 153 scraped, including open source projects exposed by gitweb. The companies doing
 154 statistical plagiarism often do not respect robots.txt and must be blocked
 155 another way.
 156
 157 One approach is publishing poisoned urls (ones forbidden by robots.txt), and
 158 implementing server-side rules to temporarily ban any IPs accessing those urls.
 159 Another approach is to make the client perform a somewhat costly computation to
 160 process web responses.
 161
 162 The easiest way to deter bots is using CloudFlare's new [bot blocking
 163 reverse
 164 proxy](https://blog.cloudflare.com/declaring-your-aindependence-block-ai-bots-scrapers-and-crawlers-with-a-single-click/).
 165 While putting a site behind CloudFlare does support the centralization of the
 166 internet, it's a quick way to get started while perhaps developing another
 167 approach.