Witch of Git - web/blog/blob - posts/2020/hosting-my-own-git.md

   1 ---
   2 title: "Hosting My Own Git"
   3 date: 2020-02-18
   4 tags:
   5 - git
   6 - web
   7 summary: "I don't want to have to use GitHub for all my personal projects while they still support ICE, so I figure out how to do my own hosting."
   8 ---
   9
  10 I've wanted to get off GitHub at least for new projects due to their [supporting ICE][], but I hadn't figured what I was going to do until recently.
  11 Then, Jordan Rose made [a post about setting up personal Git hosting][gitweb shared] that I liked, and I learned how easy it was to set up, and about [GitWeb][].
  12 So I set up my own shared Git hosting that suited my needs, which you can take a look at at [git.witchoflight.com][].
  13
  14 [supporting ice]: https://github.com/drop-ice/dear-github-2.0
  15 [gitweb shared]: https://belkadan.com/blog/2020/01/Gitweb-on-Shared-Hosting/
  16 [gitweb]: https://git-scm.com/docs/gitweb
  17 [git.witchoflight.com]: https://git.witchoflight.com
  18
  19 ### Hosting *Your* Own Git
  20
  21 It turns out if you only care about SSH access, hosting Git is way easier than I believed it would be.
  22 If you have a server with SSH access, as the user you want to use Git as, run `git init --bare` to create a repository.
  23 On my server, I created a `git` user, and a `/repos/` folder owned by the `git` user where I could create all of my repos.
  24 Then, it's just a matter of using `<user>@<server>:<path>` as your remote.
  25 With that, your git and ssh handles all of the connections and transfer, you don't need a special Git server running or anything.
  26
  27 As a specific example of using this:
  28 When I want a new repository on my server "Sunstone," I ssh there and create a new bare repository:
  29
  30 ```shell-session
  31 $ ssh sunstone
  32 $ su git
  33 $ cd /repos/
  34 $ git init --bare fancy-new-repo.git
  35 ```
  36
  37 I include the `.git` suffix as a personal preference, it's just part of the path and doesn't do anything special, so you can leave it off if you prefer.
  38 Now I can clone it as `git clone git@sunstone:/repos/fancy-new-repo.git`.
  39 You can do all sorts of setup to make this work fine for letting multiple users push, including users that don't have access to most of the computer, but I'll leave those kinds of things to [the Git docs][].
  40 There are other fancy things you can do to make it nicer, I'll get to some of those later.
  41
  42 [the git docs]: https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server
  43
  44 ### Sharing With The World
  45
  46 One of the big things that GitHub offers is the ability for anybody to easily read and clone the code without any particular authorization.
  47 It turns out that Git itself offers a solution for this, called [GitWeb][].
  48 It's a server that makes readable web pages for Git repositories, and as a side effect you can do plain HTTP(S) clones.
  49
  50 For this, I followed the setup directions [in the docs][gitweb] and in [Jordan's post][gitweb shared], as well as searching around online for various setups.
  51 In the end, I put a few pieces together which were different from what I found.
  52 My setup is a bit different from those because I'm on nginx.
  53 Like Jordan, I want people to be able to use the nice URLs, and also to clone over HTTPS.
  54
  55 #### Configuring GitWeb
  56
  57 First, `/etc/gitweb.conf`:
  58
  59 ```perl
  60 our $projectroot = "/repos";
  61 our $site_name = 'Witch of Git';
  62 our @git_base_url_list = qw(https://git.witchoflight.com);
  63 our $omit_owner = true;
  64 $feature{'highlight'}{'default'} = [1];
  65 $feature{'pathinfo'}{'default'} = [1];
  66 $feature{'search'}{'default'} = [0];
  67
  68 our %highlight_ext = (
  69     %highlight_ext,
  70     (map { $_ => $_ } qw(rs lua)),
  71     toml => 'ini',  # good enough for lazy :?
  72 );
  73
  74 @stylesheets = ("/static/gitweb.css");
  75 $logo = "/static/git-logo.png";
  76 $favicon = "/static/git-favicon.png";
  77 $javascript = "/static/gitweb.js";
  78
  79 $export_auth_hook = sub { not ($_[0] =~ /\.git\z/) };
  80 ```
  81
  82 This does a few things.
  83 First, some basic variables.
  84 Where it should look for files, what the title should be, stuff like that.
  85 I enable syntax highlighting, and importantly enable `pathinfo`, which changes URLs from messy query strings to readable URLs.
  86 If you're not careful, this can cause trouble in the server config later, but I'll go over that.
  87
  88 I need to modify `%highlight_ext`, which specifies what file extensions map to which syntax highlighting.
  89 This is based on looking at `/usr/share/gitweb/gitweb.cgi` which sets up all the features that you can modify, and it has a comment:
  90
  91 ```perl
  92 # see files in /usr/share/highlight/langDefs/ directory
  93 ```
  94
  95 Setting `pathinfo` requires that we specify the stylesheets, logo, favicon, and JS explicitly, for some reason.
  96
  97 The very last line is my own idea here.
  98 The `$export_auth_hook` is a callback that checks if a given repo should be exported.
  99 I create two copies of all my repos with a symlink, a `repo.git`, and a plain `repo` linked to the first.
 100 I create the former because I like having my remotes have `.git` on them, and I create the latter because it makes for nicer URLs in GitWeb.
 101 I use the hook here to avoid exporting two copies of each.
 102
 103 #### Nginx
 104
 105 I happen to like Nginx as a static file server.
 106 I planned to have it already running on my server, so it seemed like the best idea to get GitWeb running through there.
 107 Unfortunately, GitWeb is a CGI script, and Nginx doesn't directly support them.
 108 I searched around on three different fronts.
 109 One, tutorials for Nginx CGI scripts.
 110 Another, tutorials for setting up GitWeb with other servers.
 111 And also in the middle of those, tutorials actually on GitWeb with Nginx.
 112 They didn't completely solve my issues, but I used [a tutorial from the Arch wiki][] and [a tutorial in a gist][].
 113
 114 Synthesizing all this together, I made my `/etc/nginx/sites-available/gitweb`:
 115 ```nginx
 116 server {
 117     listen 80 default_server;
 118     listen [::]:80 default_server;
 119     server_name git.witchoflight.com;
 120     root /repos/;
 121
 122     location / {
 123         try_files $uri @gitweb;
 124     }
 125
 126     location /static/ {
 127         root /usr/share/gitweb/;
 128     }
 129
 130     location @gitweb {
 131         include fastcgi_params;
 132         gzip off;
 133         fastcgi_param SCRIPT_FILENAME /usr/share/gitweb/gitweb.cgi;
 134         fastcgi_param PATH_INFO $uri;
 135         fastcgi_param GITWEB_CONFIG /etc/gitweb.conf;
 136         fastcgi_pass unix:/var/run/fcgiwrap.socket;
 137     }
 138 }
 139 ```
 140
 141 This will try to route files at the root through GitWeb, and files under `/static/` to the filesystem.
 142 GitWeb is set up as a fastcgi client, with fastcgi configured to run through `fcgiwrap.socket`.
 143 I pass the request uri in the `PATH_INFO`, seems to be necessary to handle routing with the pretty paths.
 144 As the absolute basics, you always have to pass the script filename, and the config.
 145 I actually got stuck for about an hour here with a mismatch between `fcgiwrap.socket` and `fcgiwrap.sock`, so check your spellings carefully while you configure things!
 146 With this setup, GitWeb will correctly format HTML pages when it should, and also correctly pass through files inside the repositories so that HTTP(S) cloning works fine.
 147 Speaking of HTTPS...
 148
 149 [a tutorial from the arch wiki]: https://wiki.archlinux.org/index.php/Gitweb#Nginx
 150 [a tutorial in a gist]: https://gist.github.com/mcxiaoke/055af99e86f8e8d3176e
 151
 152 #### Using HTTPS
 153
 154 As my final step, I got a cert set up for HTTPS.
 155 I've never set up my own HTTPS before, just used it if it was provided by my hosting, but setting one up with [Let's Encrypt][letsencrypt] ended up being quite easy.
 156 I just directly followed the steps on their "Get Started" page and things worked first try.
 157 I pointed it at my GitWeb Nginx config and it slightly rewrote it to add certs and things, which I left out above.
 158
 159 [letsencrypt]: https://letsencrypt.org/
 160
 161 ### Making It Nice
 162
 163 I do *lots* of hobby projects, so I want it to be nice to set up repos.
 164 In the `git` user's home directory, I have a `git-hooks/` folder that holds all of the "universal" base hooks I come up with, a `git-template/` folder that stores the template for new git repos, and a `make-repo` script which does the setup for new repositories.
 165
 166 First, the `git-hooks/`.
 167 I have a dedicated folder for them so the template can symlink that, so I don't need to edit all the different hooks.
 168 Currently I just have one, the `post-update` hook.
 169 It contains:
 170
 171 ```bash
 172 #!/bin/sh
 173 git update-server-info
 174 git cat-file blob HEAD:README.md | pulldown-cmark > README.html
 175 ```
 176
 177 We need to `git update-server-info` to prepare the data that HTTP clones and things need.
 178 Then, we prepare the `README.html` file that GitWeb displays on the main page of a project.
 179 For this, `git cat-file blob HEAD:README.md` grabs the latest `README.md` from the main branch, and then we render it to HTML.
 180
 181 In the `git-template/` folder, I make symlinks from the `~/git-hooks/` folder into the `git-template/hooks/` folder so they just need to be updated in one place.
 182 I also change the default branch to `develop` since I prefer that instead of `master`.
 183 You can set the template dir with `git config --global init.templatedir <path>`.
 184
 185 And then the `make-repo` script I just have set up so that it will create both `repo` and `repo.git` in the right place when I ask for it, and let me rewrite the description immediately.
 186
 187 ```bash
 188 #!/bin/bash
 189 set -e
 190
 191 if [ -z $1 ]; then
 192         echo "Usage: make-repo <name>"
 193         exit 0
 194 fi
 195 # Strip .git from the name if you specify it, for uniformity
 196 repo=$(basename -s.git $1)
 197 # We don't want to work as root, but we login as root (oops?)
 198 # so it's convenient to automatically switch to the git user
 199 if [ "$EUID" -eq 0 ]; then exec su git -c "$0 $1"; fi
 200 # Only allow running as the git user, for file permissions purposes
 201 if [ $(whoami) != "git" ]; then
 202         echo "Please run this tool as the 'git' user"
 203         exit 1
 204 fi
 205 # Don't overwrite existing repositories
 206 if [ -d "/repos/$repo.git" ]; then
 207         echo "Repository '$1' already exists"
 208         exit 2
 209 fi
 210
 211 cd /repos/
 212 # Make a bare repo for SSH cloning
 213 git init --bare "$repo.git"
 214 # We immediately edit the description file that will show up in GitWeb
 215 sensible-editor "$repo.git/description"
 216 # And have both repo and repo.git point to the same place for cloning
 217 ln -s "$repo.git" "$repo"
 218 ```
 219
 220 ### What Now?
 221
 222 Well, now I have Git hosting!
 223 And if you want some, you can probably figure it out too, it's less work than I thought it might be!
 224 I've done some minimal styling, making it a narrower column and fixing some things, but I want to do more.
 225 That's a project for another day, though.
 226
 227 Now, go look at my projects.
 228 Some of them are cool!
 229 I'll try to write about them soon. :)
 230 [git.witchoflight.com][].