doc/install/install-arv-git-httpd.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: installguide
   4 title: Install the Git server
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 # "Introduction":#introduction
  13 # "Install dependencies":#dependencies
  14 # "Create "git" user and storage directory":#create
  15 # "Install gitolite":#gitolite
  16 # "Configure gitolite":#config-gitolite
  17 # "Configure git synchronization":#sync
  18 # "Update config.yml":#update-config
  19 # "Update nginx configuration":#update-nginx
  20 # "Install arvados-git-httpd package":#install-packages
  21 # "Restart the API server and controller":#restart-api
  22 # "Confirm working installation":#confirm-working
  23
  24 h2(#introduction). Introduction
  25
  26 Arvados support for git repository management enables using Arvados permissions to control access to git repositories.  Users can create their own private and public git repositories and share them with others.
  27
  28 The git hosting setup involves three components.
  29 * The "arvados-git-sync.rb" script polls the API server for the current list of repositories, creates bare repositories, and updates the local permission cache used by gitolite.
  30 * Gitolite provides SSH access.  Users authenticate by SSH keys.
  31 * arvados-git-http provides HTTPS access.  Users authenticate by Arvados tokens.
  32
  33 Git services must be installed on the same host as the Arvados Rails API server.
  34
  35 h2(#dependencies). Install dependencies
  36
  37 h3. Alma/CentOS/Red Hat/Rocky
  38
  39 <notextile>
  40 <pre><code># <span class="userinput">dnf install git perl-Data-Dumper openssh-server</span>
  41 </code></pre>
  42 </notextile>
  43
  44 h3. Debian and Ubuntu
  45
  46 <notextile>
  47 <pre><code># <span class="userinput">apt-get --no-install-recommends install git openssh-server</span>
  48 </code></pre>
  49 </notextile>
  50
  51 h2(#create). Create "git" user and storage directory
  52
  53 Gitolite and some additional scripts will be installed in @/var/lib/arvados/git@, which means hosted repository data will be stored in @/var/lib/arvados/git/repositories@. If you choose to install gitolite in a different location, make sure to update the @git_repositories_dir@ entry in your API server's @application.yml@ file accordingly: for example, if you install gitolite at @/data/gitolite@ then your @git_repositories_dir@ will be @/data/gitolite/repositories@.
  54
  55 A new UNIX account called "git" will own the files. This makes git URLs look familiar to users (<code>git@[...]:username/reponame.git</code>).
  56
  57 On Debian- or Red Hat-based systems:
  58
  59 <notextile>
  60 <pre><code>gitserver:~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
  61 gitserver:~$ <span class="userinput">sudo useradd --comment git --home-dir /var/lib/arvados/git git</span>
  62 gitserver:~$ <span class="userinput">sudo chown -R git:git ~git</span>
  63 </code></pre>
  64 </notextile>
  65
  66 The git user needs its own SSH key. (It must be able to run <code>ssh git@localhost</code> from scripts.)
  67
  68 <notextile>
  69 <pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
  70 git@gitserver:~$ <span class="userinput">ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa</span>
  71 git@gitserver:~$ <span class="userinput">cp .ssh/id_rsa.pub .ssh/authorized_keys</span>
  72 git@gitserver:~$ <span class="userinput">ssh -o stricthostkeychecking=no localhost cat .ssh/id_rsa.pub</span>
  73 Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
  74 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver
  75 git@gitserver:~$ <span class="userinput">rm .ssh/authorized_keys</span>
  76 </code></pre>
  77 </notextile>
  78
  79 h2(#gitolite). Install gitolite
  80
  81 Check "https://github.com/sitaramc/gitolite/tags":https://github.com/sitaramc/gitolite/tags for the latest stable version. This guide was tested with @v3.6.11@. _Versions below 3.0 are missing some features needed by Arvados, and should not be used._
  82
  83 Download and install the version you selected.
  84
  85 <notextile>
  86 <pre><code>$ <span class="userinput">sudo -u git -i bash</span>
  87 git@gitserver:~$ <span class="userinput">echo 'PATH=$HOME/bin:$PATH' &gt;.profile</span>
  88 git@gitserver:~$ <span class="userinput">. .profile</span>
  89 git@gitserver:~$ <span class="userinput">git clone --branch <b>v3.6.11</b> https://github.com/sitaramc/gitolite</span>
  90 ...
  91 Note: checking out '5d24ae666bfd2fa9093d67c840eb8d686992083f'.
  92 ...
  93 git@gitserver:~$ <span class="userinput">mkdir bin</span>
  94 git@gitserver:~$ <span class="userinput">gitolite/install -ln ~git/bin</span>
  95 git@gitserver:~$ <span class="userinput">bin/gitolite setup -pk .ssh/id_rsa.pub</span>
  96 Initialized empty Git repository in /var/lib/arvados/git/repositories/gitolite-admin.git/
  97 Initialized empty Git repository in /var/lib/arvados/git/repositories/testing.git/
  98 WARNING: /var/lib/arvados/git/.ssh/authorized_keys missing; creating a new one
  99     (this is normal on a brand new install)
 100 </code></pre>
 101 </notextile>
 102
 103 _If this didn't go well, more detail about installing gitolite, and information about how it works, can be found on the "gitolite home page":http://gitolite.com/._
 104
 105 Clone the gitolite-admin repository. The arvados-git-sync.rb script works by editing the files in this working directory and pushing them to gitolite. Here we make sure "git push" won't produce any errors or warnings.
 106
 107 <notextile>
 108 <pre><code>git@gitserver:~$ <span class="userinput">git clone git@localhost:gitolite-admin</span>
 109 Cloning into 'gitolite-admin'...
 110 remote: Counting objects: 6, done.
 111 remote: Compressing objects: 100% (4/4), done.
 112 remote: Total 6 (delta 0), reused 0 (delta 0)
 113 Receiving objects: 100% (6/6), done.
 114 Checking connectivity... done.
 115 git@gitserver:~$ <span class="userinput">cd gitolite-admin</span>
 116 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.email arvados</span>
 117 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.name arvados</span>
 118 git@gitserver:~/gitolite-admin$ <span class="userinput">git config push.default simple</span>
 119 git@gitserver:~/gitolite-admin$ <span class="userinput">git push</span>
 120 Everything up-to-date
 121 </code></pre>
 122 </notextile>
 123
 124 h2(#config-gitolite). Configure gitolite
 125
 126 Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
 127
 128 Add the following lines to the top of @~git/.gitolite.rc@:
 129
 130 <notextile>
 131 <pre><code><span class="userinput">my $repo_aliases;
 132 my $aliases_src = "$ENV{HOME}/.gitolite/arvadosaliases.pl";
 133 if ($ENV{HOME} && (-e $aliases_src)) {
 134     $repo_aliases = do $aliases_src;
 135 }
 136 $repo_aliases ||= {};
 137 </span></code></pre>
 138 </notextile>
 139
 140 Add the following lines inside the section that begins @%RC = (@:
 141
 142 <notextile>
 143 <pre><code><span class="userinput">    REPO_ALIASES => $repo_aliases,
 144 </span></code></pre>
 145 </notextile>
 146
 147 Inside that section, adjust the 'UMASK' setting to @022@, to ensure the API server has permission to read repositories:
 148
 149 <notextile>
 150 <pre><code>    UMASK => <span class="userinput">022</span>,
 151 </code></pre>
 152 </notextile>
 153
 154 Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
 155
 156 <notextile>
 157 <pre><code><span class="userinput">            # access a repo by another (possibly legacy) name
 158             'Alias',
 159 </span></code></pre>
 160 </notextile>
 161
 162 h2(#sync). Configure git synchronization
 163
 164 Create a configuration file @/var/www/arvados-api/current/config/arvados-clients.yml@ using the following template, filling in the appropriate values for your system.
 165 * For @arvados_api_token@, use @SystemRootToken@
 166 * For @gitolite_arvados_git_user_key@, provide the public key you generated above, i.e., the contents of @~git/.ssh/id_rsa.pub@.
 167
 168 <notextile>
 169 <pre><code>production:
 170   gitolite_url: /var/lib/arvados/git/repositories/gitolite-admin.git
 171   gitolite_tmp: /var/lib/arvados/git
 172   arvados_api_host: <span class="userinput">ClusterID.example.com</span>
 173   arvados_api_token: "<span class="userinput">zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>"
 174   arvados_api_host_insecure: <span class="userinput">false</span>
 175   gitolite_arvados_git_user_key: "<span class="userinput">ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver</span>"
 176 </code></pre>
 177 </notextile>
 178
 179 <pre>
 180 $ sudo chown git:git /var/www/arvados-api/current/config/arvados-clients.yml
 181 $ sudo chmod og-rwx /var/www/arvados-api/current/config/arvados-clients.yml
 182 </pre>
 183
 184 h3. Test configuration
 185
 186 notextile. <pre><code>$ <span class="userinput">sudo -u git -i bash -c 'cd /var/www/arvados-api/current && bin/bundle exec script/arvados-git-sync.rb production'</span></code></pre>
 187
 188 h3. Enable the synchronization script
 189
 190 The API server package includes a script that retrieves the current set of repository names and permissions from the API, writes them to @arvadosaliases.pl@ in a format usable by gitolite, and triggers gitolite hooks which create new empty repositories if needed. This script should run every 2 to 5 minutes.
 191
 192 Create @/etc/cron.d/arvados-git-sync@ with the following content:
 193
 194 <notextile>
 195 <pre><code><span class="userinput">*/5 * * * * git cd /var/www/arvados-api/current && bin/bundle exec script/arvados-git-sync.rb production</span>
 196 </code></pre>
 197 </notextile>
 198
 199 h2(#update-config). Update config.yml
 200
 201 Edit the cluster config at @config.yml@ .
 202
 203 <notextile>
 204 <pre><code>    Services:
 205       GitSSH:
 206         ExternalURL: "<span class="userinput">ssh://git@git.ClusterID.example.com</span>"
 207       GitHTTP:
 208         ExternalURL: <span class="userinput">https://git.ClusterID.example.com/</span>
 209         InternalURLs:
 210           "http://localhost:9001": {}
 211     Git:
 212       GitCommand: <span class="userinput">/var/lib/arvados/git/gitolite/src/gitolite-shell</span>
 213       GitoliteHome: <span class="userinput">/var/lib/arvados/git</span>
 214       Repositories: <span class="userinput">/var/lib/arvados/git/repositories</span>
 215 </code></pre>
 216 </notextile>
 217
 218 h2(#update-nginx). Update nginx configuration
 219
 220 Use a text editor to create a new file @/etc/nginx/conf.d/arvados-git.conf@ with the following configuration.  Options that need attention are marked in <span class="userinput">red</span>.
 221
 222 <notextile>
 223 <pre><code>upstream arvados-git-httpd {
 224   server                  127.0.0.1:<span class="userinput">9001</span>;
 225 }
 226 server {
 227   listen                  443 ssl;
 228   server_name             git.<span class="userinput">ClusterID.example.com</span>;
 229   proxy_connect_timeout   90s;
 230   proxy_read_timeout      300s;
 231
 232   ssl_certificate         <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
 233   ssl_certificate_key     <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
 234
 235   # The server needs to accept potentially large refpacks from push clients.
 236   client_max_body_size 128m;
 237
 238   location  / {
 239     proxy_pass            http://arvados-git-httpd;
 240   }
 241 }
 242 </code></pre>
 243 </notextile>
 244
 245 h2(#install-packages). Install the arvados-git-httpd package
 246
 247 The arvados-git-httpd package provides HTTP access, using Arvados authentication tokens instead of passwords. It must be installed on the system where your git repositories are stored.
 248
 249 h3. Alma/CentOS/Red Hat/Rocky
 250
 251 <notextile>
 252 <pre><code># <span class="userinput">dnf install arvados-git-httpd</span>
 253 </code></pre>
 254 </notextile>
 255
 256 h3. Debian and Ubuntu
 257
 258 <notextile>
 259 <pre><code># <span class="userinput">apt-get --no-install-recommends install arvados-git-httpd</span>
 260 </code></pre>
 261 </notextile>
 262
 263 h2(#restart-api). Restart the API server and controller
 264
 265 After adding Workbench to the Services section, make sure the cluster config file is up to date on the API server host, and restart the API server and controller processes to ensure the changes are applied.
 266
 267 <notextile>
 268 <pre><code># <span class="userinput">systemctl restart nginx arvados-controller</span>
 269 </code></pre>
 270 </notextile>
 271
 272 h2(#confirm-working). Confirm working installation
 273
 274 Create 'testrepo' in the Arvados database.
 275
 276 <notextile>
 277 <pre><code>~$ <span class="userinput">arv --format=uuid repository create --repository '{"name":"myusername/testrepo"}'</span>
 278 </code></pre></notextile>
 279
 280 The arvados-git-sync cron job will notice the new repository record and create a repository on disk.  Because it is on a timer (default 5 minutes) you may have to wait a minute or two for it to show up.
 281
 282 h3. SSH
 283
 284 Before you do this, go to Workbench and choose *SSH Keys* from the menu, and upload your public key.  Arvados uses the public key to identify you when you access the git repo.
 285
 286 <notextile>
 287 <pre><code>~$ <span class="userinput">git clone git@git.ClusterID.example.com:username/testrepo.git</span>
 288 </code></pre>
 289 </notextile>
 290
 291 h3. HTTP
 292
 293 Set up git credential helpers as described in "install shell server":install-shell-server.html#config-git for the git command to use your API token instead of prompting you for a username and password.
 294
 295 <notextile>
 296 <pre><code>~$ <span class="userinput">git clone https://git.ClusterID.example.com/username/testrepo.git</span>
 297 </code></pre>
 298 </notextile>