1---
  2title: run cgit on openbsd
  3date: 2021-01-06T13:30+03:00
  4author: la-ninpre
  5tags: openbsd git tutorial
  6---
  7
  8i started using git for my personal pet projects. a little time then i decided
  9that it would be a nice idea to make them as open as i can. i use github, but
 10to support that idea of self-hosting, i wanted some free and easy web frontend
 11to git. cgit is one of the most popular ones, but it was kinda tough to run on
 12openbsd.
 13
 14<!--more-->
 15
 16i know gitweb exists, but i just like cgit more.
 17
 18cgit is quite easy to install still, but needs some work done, it's not like
 19two commands.
 20
 21[official cgit page][1] has some installation instructions. it mentions that
 22it's distributed in binary form for some linux distros, but of course openbsd's
 23not there, so we'll need to build it from source.
 24
 25first of all, i wanted to use openbsd's native web server`httpd` and native
 26fastcgi server -- `slowcgi`.
 27the issue is that openbsd's httpd web server lives in chroot-jail and that fact
 28is complicating the configuration.
 29but before we need to build cgit from source.
 30
 31## building cgit
 32
 33to do that, clone cgit source code from [official cgit page][1]
 34(or if you like [my cgit page][2], you can clone it instead):
 35
 36```
 37$ git clone https://git.zx2c4.com/cgit
 38```
 39
 40then move to this directory:
 41
 42```
 43$ cd cgit
 44```
 45
 46there are some source files and a Makefile. by default, it'll install cgit in
 47`/var/www/htdocs/cgit`. if you want a different path, make corresponding change
 48in a Makefile by editing `CGIT_SCRIPT_PATH` variable.
 49
 50but before compiling cgit itself, we need to init and build git submodule
 51(i suppose, this is the source code of git itself that is needed to make some
 52git operations on repositories):
 53
 54```
 55$ git submodule init
 56$ git submodule update
 57```
 58
 59and then we can compile cgit. note that gnu version of make utility is used,
 60install `gmake` from openbsd repositories (`doas pkg add gmake`):
 61
 62```
 63$ gmake && doas gmake install
 64```
 65
 66notice that this command should be executed by user who has write permissions
 67to `/var/www` and `/usr/local/lib` (usually root).
 68
 69when it's done, the rest is to create directories needed for cgit to work
 70and also to configure `httpd` and `slowcgi`.
 71
 72## creating directories and dev/null
 73
 74cgit uses following files to work:
 75- `/etc/cgitrc` -- needed for configuration
 76  (see [man page][3] for available options)
 77- `/var/cache/cgit` -- cache that is used by cgit to reduce cpu usage
 78- `/var/www/htdocs/cgit/`
 79  - `cgit.css` -- stylesheet
 80  - `cgit.png` -- logo
 81  - `favicon.ico` -- favicon
 82  - `robots.txt` -- instructions for indexers
 83- `/usr/local/lib/cgit/*` -- different filters and stuff
 84  (i didn't need it at all, because it's hard to make it work in a chroot)
 85- `/dev/null` -- i don't know exactly why it's needed, but it won't work without
 86  it
 87
 88because cgit will run in chroot-jail, all those files and directories except
 89`/var/www/htdocs/cgit` should be located in `/var/www`
 90(e.g. `/var/www/etc/cgitrc` and so on).
 91
 92```
 93$ doas mkdir -p /var/www/{cache/cgit,dev,etc,usr/lib,usr/libexec}
 94$ doas chown -R www:www /var/www/{cache/cgit,htdocs/cgit}
 95```
 96
 97`/dev/null` is not a regular file, it's a device, so it must be created using:
 98
 99```
100$ doas install -d -g daemon /template/dev
101$ cd /template/dev
102$ doas mknod -m 666 null c 2 2
103$ doas mount_mfs -s 1M -P /template/dev /dev/sd0b /var/www/dev
104```
105
106this instruction is taken from [fossil docs][4].
107
108## copying libraries
109
110since cgit is not linked statically, it also needs some dynamic libraries.
111they all need to be accessible from chroot, so we need to copy them to
112`/var/www/usr/lib`. to check, what should be copied, run:
113
114```
115$ ldd /var/www/htdocs/cgit/cgit.cgi
116
117/var/www/htdocs/cgit/cgit.cgi:
118	Start            End              Type  Open Ref GrpRef Name
119	00000b068a590000 00000b068a7b6000 exe   2    0   0      /var/www/htdocs/cgit/cgit.cgi
120	00000b0927dcb000 00000b0927de7000 rlib  0    1   0      /usr/lib/libz.so.5.0
121	00000b0937409000 00000b093750b000 rlib  0    2   0      /usr/local/lib/libiconv.so.7.0
122	00000b0978c28000 00000b0978c37000 rlib  0    1   0      /usr/local/lib/libintl.so.7.0
123	00000b091fdc0000 00000b091fdcc000 rlib  0    2   0      /usr/lib/libpthread.so.26.1
124	00000b0920331000 00000b09203be000 rlib  0    1   0      /usr/local/lib/libluajit-5.1.so.1.0
125	00000b091cc5f000 00000b091cd54000 rlib  0    1   0      /usr/lib/libc.so.96.0
126	00000b089fffb000 00000b08a002b000 rlib  0    1   0      /usr/lib/libm.so.10.1
127	00000b08b2542000 00000b08b2585000 rlib  0    1   0      /usr/lib/libc++abi.so.3.0
128	00000b08cebc7000 00000b08cebc7000 ld.so 0    1   0      /usr/libexec/ld.so
129```
130
131and it'll return a list of all dependencies. copy them to `/var/www/lib`:
132
133```
134$ doas cp /usr/lib/{libz.so.5.0,libpthread.so.26.1,libc.so.96.0,libm.so.10.1,libc++abi.so.3.0} /var/www/lib
135$ doas cp /usl/local/lib/{libiconv.so.7.0,libintl.so.7.0,libluajit-5.1.so.1.0} /var/www/lib
136$ doas cp /usr/libexec/ld.so /var/www/usr/libexec
137```
138
139you should be able now to test cgit using this command:
140
141```
142$ doas chroot -u www /var/www /htdocs/cgit/cgit.cgi
143```
144
145it should return no errors but a webpage.
146
147## configuring cgit
148
149as already mentioned, cgit is configured using `/var/www/etc/cgitrc`. i suggest
150reading [manpage][3] for detailed overview of all available options, but here's
151an example cgitrc to start with:
152
153```
154#cache
155cache-size=1000
156cache-dynamic-ttl=60
157cache-static-ttl=44640
158cache-root-ttl=6
159cache-repo=5
160
161#index page
162enable-index-links=1
163enable-index-owner=0
164max-repodesc-length=60
165root-title=aaoth's git repos
166root-desc=some personal projects
167
168#repo global
169enable-git-config=1
170enable-commit-graph=1
171enable-follow-links=1
172enable-blame=1
173enable-http-clone=1
174enable-log-filecount=1
175enable-log-linecount=1
176enable-html-serving=1
177branch-sort=age
178snapshots=tar.gz zip
179side-by-side-diffs=0
180max-stats=week
181
182#root
183readme=:README.md
184readme=:readme.md
185readme=:README
186readme=:readme
187
188#mimetypes
189mimetype.html=text/html
190mimetype.gif=image/gif
191mimetype.jpg=image/jpeg
192mimetype.jpeg=image/jpeg
193mimetype.png=image/png
194mimetype.svg=image/svg+xml
195mimetype.pdf=application/pdf
196
197scan-path=/git
198```
199
200some of the settings are omitted, but you can tweak it further as you wish.
201
202note that i use autoscan feature of cgit. i have all my repos located in
203`var/www/git` as described by `scan-path` option.
204all of them are chowned by www user and have `cgitrc` text file inside.
205
206each repo-specific `cgitrc` looks like this:
207
208```
209name=test_repo
210desc=test repository to test cgit
211owner=username
212max-stats=month
213```
214
215## configuring httpd and slowcgi
216
217and now the last part is to actually serve cgit using httpd and slowcgi
218
219first of all, enable and start slowcgi:
220
221```
222$ doas rcctl enable slowcgi
223$ doas rcctl start slowcgi
224```
225
226then edit your `/etc/httpd.conf`, you need to create a simple server statement
227
228```
229server "example.com" {
230
231    listen on egress port 80
232    root "/htdocs/cgit"
233
234    location "/cgit.css" {
235        root "/htdocs/cgit"
236    }
237
238    location "/cgit.png" {
239        root "/htdocs/cgit"
240    }
241
242    location "/robots.txt" {
243        root "/htdocs/cgit"
244    }
245
246    location "/favicon.ico" {
247        root "/htdocs/cgit"
248    }
249
250    location "/*" {
251        fastcgi {
252            socket "/run/slowcgi.sock"
253            param SCRIPT_FILENAME "/htdocs/cgit/cgit.cgi"
254        }
255    }
256}
257```
258
259i know it can seem *very* odd, but it's the only way it works for me. as always,
260all improvement suggestions are welcome.
261
262and finally, (re-)start httpd:
263
264```
265$ doas rcctl enable httpd
266$ doas rcctl start httpd
267```
268
269[1]:https://git.zx2c4.com/cgit
270[2]:https://git.aaoth.xyz/cgit/cgit.git
271[3]:https://git.zx2c4.com/cgit/tree/cgitrc.5.txt
272[4]:https://www.fossil-scm.org/home/doc/trunk/www/server/openbsd/fastcgi.md#chroot