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 Arvados allows users to create their own private and public git repositories, and clone/push them using SSH and HTTPS.
  13
  14 The git hosting setup involves three components.
  15 * 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.
  16 * Gitolite provides SSH access.
  17 * arvados-git-http provides HTTPS access.
  18
  19 It is not strictly necessary to deploy _both_ SSH and HTTPS access, but we recommend deploying both:
  20 * SSH is a more appropriate way to authenticate from a user's workstation because it does not require managing tokens on the client side;
  21 * HTTPS is a more appropriate way to authenticate from a shell VM because it does not depend on SSH agent forwarding (SSH clients' agent forwarding features tend to behave as if the remote machine is fully trusted).
  22
  23 The HTTPS instructions given below will not work if you skip the SSH setup steps.
  24
  25 h2. Set up DNS
  26
  27 By convention, we use the following hostname for the git service:
  28
  29 <notextile>
  30 <pre><code>git.<span class="userinput">uuid_prefix</span>.your.domain
  31 </code></pre>
  32 </notextile>
  33
  34 {% include 'notebox_begin' %}
  35 Here, we show how to install the git hosting services *on the same host as your API server.* Using a different host is not yet fully supported. On this page we will refer to it as your git server.
  36 {% include 'notebox_end' %}
  37
  38 DNS and network configuration should be set up so port 443 reaches your HTTPS proxy, and port 22 reaches the OpenSSH service on your git server.
  39
  40 h2. Generate an API token
  41
  42 {% assign railshost = "gitserver" %}
  43 {% assign railscmd = "bundle exec ./script/create_superuser_token.rb" %}
  44 {% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
  45 Use the following command to generate an API token.  {% include 'install_rails_command' %}
  46
  47 Copy that token; you'll need it in a minute.
  48
  49 h2. Install git and other dependencies
  50
  51 On Debian-based systems:
  52
  53 <notextile>
  54 <pre><code>gitserver:~$ <span class="userinput">sudo apt-get install git openssh-server</span>
  55 </code></pre>
  56 </notextile>
  57
  58 On Red Hat-based systems:
  59
  60 <notextile>
  61 <pre><code>gitserver:~$ <span class="userinput">sudo yum install git perl-Data-Dumper openssh-server</span>
  62 </code></pre>
  63 </notextile>
  64
  65 {% include 'install_git' %}
  66
  67 h2. Create a "git" user and a storage directory
  68
  69 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@.
  70
  71 A new UNIX account called "git" will own the files. This makes git URLs look familiar to users (<code>git@[...]:username/reponame.git</code>).
  72
  73 On Debian- or Red Hat-based systems:
  74
  75 <notextile>
  76 <pre><code>gitserver:~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
  77 gitserver:~$ <span class="userinput">sudo useradd --comment git --home-dir /var/lib/arvados/git git</span>
  78 gitserver:~$ <span class="userinput">sudo chown -R git:git ~git</span>
  79 </code></pre>
  80 </notextile>
  81
  82 The git user needs its own SSH key. (It must be able to run <code>ssh git@localhost</code> from scripts.)
  83
  84 <notextile>
  85 <pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
  86 git@gitserver:~$ <span class="userinput">ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa</span>
  87 git@gitserver:~$ <span class="userinput">cp .ssh/id_rsa.pub .ssh/authorized_keys</span>
  88 git@gitserver:~$ <span class="userinput">ssh -o stricthostkeychecking=no localhost cat .ssh/id_rsa.pub</span>
  89 Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
  90 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver
  91 git@gitserver:~$ <span class="userinput">rm .ssh/authorized_keys</span>
  92 </code></pre>
  93 </notextile>
  94
  95 h2. Install gitolite
  96
  97 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.4@. _Versions below 3.0 are missing some features needed by Arvados, and should not be used._
  98
  99 Download and install the version you selected.
 100
 101 <notextile>
 102 <pre><code>git@gitserver:~$ <span class="userinput">echo 'PATH=$HOME/bin:$PATH' &gt;.profile</span>
 103 git@gitserver:~$ <span class="userinput">source .profile</span>
 104 git@gitserver:~$ <span class="userinput">git clone --branch <b>v3.6.4</b> https://github.com/sitaramc/gitolite</span>
 105 ...
 106 Note: checking out '5d24ae666bfd2fa9093d67c840eb8d686992083f'.
 107 ...
 108 git@gitserver:~$ <span class="userinput">mkdir bin</span>
 109 git@gitserver:~$ <span class="userinput">gitolite/install -ln ~git/bin</span>
 110 git@gitserver:~$ <span class="userinput">bin/gitolite setup -pk .ssh/id_rsa.pub</span>
 111 Initialized empty Git repository in /var/lib/arvados/git/repositories/gitolite-admin.git/
 112 Initialized empty Git repository in /var/lib/arvados/git/repositories/testing.git/
 113 WARNING: /var/lib/arvados/git/.ssh/authorized_keys missing; creating a new one
 114     (this is normal on a brand new install)
 115 </code></pre>
 116 </notextile>
 117
 118 _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/._
 119
 120 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.
 121
 122 <notextile>
 123 <pre><code>git@gitserver:~$ <span class="userinput">git clone git@localhost:gitolite-admin</span>
 124 Cloning into 'gitolite-admin'...
 125 remote: Counting objects: 6, done.
 126 remote: Compressing objects: 100% (4/4), done.
 127 remote: Total 6 (delta 0), reused 0 (delta 0)
 128 Receiving objects: 100% (6/6), done.
 129 Checking connectivity... done.
 130 git@gitserver:~$ <span class="userinput">cd gitolite-admin</span>
 131 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.email arvados</span>
 132 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.name arvados</span>
 133 git@gitserver:~/gitolite-admin$ <span class="userinput">git config push.default simple</span>
 134 git@gitserver:~/gitolite-admin$ <span class="userinput">git push</span>
 135 Everything up-to-date
 136 </code></pre>
 137 </notextile>
 138
 139 h3. Configure gitolite
 140
 141 Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
 142
 143 Add the following lines to the top of @~git/.gitolite.rc@:
 144
 145 <notextile>
 146 <pre><code><span class="userinput">my $repo_aliases;
 147 my $aliases_src = "$ENV{HOME}/.gitolite/arvadosaliases.pl";
 148 if ($ENV{HOME} && (-e $aliases_src)) {
 149     $repo_aliases = do $aliases_src;
 150 }
 151 $repo_aliases ||= {};
 152 </span></code></pre>
 153 </notextile>
 154
 155 Add the following lines inside the section that begins @%RC = (@:
 156
 157 <notextile>
 158 <pre><code><span class="userinput">    REPO_ALIASES => $repo_aliases,
 159 </span></code></pre>
 160 </notextile>
 161
 162 Inside that section, adjust the 'UMASK' setting to @022@, to ensure the API server has permission to read repositories:
 163
 164 <notextile>
 165 <pre><code>    UMASK => <span class="userinput">022</span>,
 166 </code></pre>
 167 </notextile>
 168
 169 Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
 170
 171 <notextile>
 172 <pre><code><span class="userinput">            # access a repo by another (possibly legacy) name
 173             'Alias',
 174 </span></code></pre>
 175 </notextile>
 176
 177 h2. Configure git synchronization
 178
 179 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.
 180 * For @arvados_api_token@, use the token you generated above.
 181 * For @gitolite_arvados_git_user_key@, provide the public key you generated above, i.e., the contents of @~git/.ssh/id_rsa.pub@.
 182
 183 <notextile>
 184 <pre><code>production:
 185   gitolite_url: /var/lib/arvados/git/repositories/gitolite-admin.git
 186   gitolite_tmp: /var/lib/arvados/git
 187   arvados_api_host: <span class="userinput">uuid_prefix.example.com</span>
 188   arvados_api_token: "<span class="userinput">zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>"
 189   arvados_api_host_insecure: <span class="userinput">false</span>
 190   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>"
 191 </code></pre>
 192 </notextile>
 193
 194 h3. Enable the synchronization script
 195
 196 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.
 197
 198 If you are using RVM, create @/etc/cron.d/arvados-git-sync@ with the following content:
 199
 200 <notextile>
 201 <pre><code><span class="userinput">*/5 * * * * git cd /var/www/arvados-api/current && /usr/local/rvm/bin/rvm-exec default bundle exec script/arvados-git-sync.rb production</span>
 202 </code></pre>
 203 </notextile>
 204
 205 Otherwise, create @/etc/cron.d/arvados-git-sync@ with the following content:
 206
 207 <notextile>
 208 <pre><code><span class="userinput">*/5 * * * * git cd /var/www/arvados-api/current && bundle exec script/arvados-git-sync.rb production</span>
 209 </code></pre>
 210 </notextile>
 211
 212 h3. Configure the API server to advertise the correct SSH URLs
 213
 214 In your API server's @application.yml@ file, add the following entry:
 215
 216 <notextile>
 217 <pre><code>git_repo_ssh_base: "git@git.<span class="userinput">uuid_prefix.your.domain</span>:"
 218 </code></pre>
 219 </notextile>
 220
 221 Make sure to include the trailing colon.
 222
 223 h2. Install the arvados-git-httpd package
 224
 225 This is needed only for HTTPS access.
 226
 227 The arvados-git-httpd package provides HTTP access, using Arvados authentication tokens instead of passwords. It is intended to be installed on the system where your git repositories are stored, and accessed through a web proxy that provides SSL support.
 228
 229 On Debian-based systems:
 230
 231 <notextile>
 232 <pre><code>~$ <span class="userinput">sudo apt-get install git arvados-git-httpd</span>
 233 </code></pre>
 234 </notextile>
 235
 236 On Red Hat-based systems:
 237
 238 <notextile>
 239 <pre><code>~$ <span class="userinput">sudo yum install git arvados-git-httpd</span>
 240 ~$ <span class="userinput">sudo systemctl enable arvados-git-httpd</span>
 241 </code></pre>
 242 </notextile>
 243
 244 Verify that @arvados-git-httpd@ and @git-http-backend@ can be run:
 245
 246 <notextile>
 247 <pre><code>~$ <span class="userinput">arvados-git-httpd -h</span>
 248 [...]
 249 Usage: arvados-git-httpd [-config path/to/arvados/git-httpd.yml]
 250 [...]
 251 ~$ <span class="userinput">git http-backend</span>
 252 Status: 500 Internal Server Error
 253 Expires: Fri, 01 Jan 1980 00:00:00 GMT
 254 Pragma: no-cache
 255 Cache-Control: no-cache, max-age=0, must-revalidate
 256
 257 fatal: No REQUEST_METHOD from server
 258 </code></pre>
 259 </notextile>
 260
 261 h3. Enable arvados-git-httpd
 262
 263 {% include 'notebox_begin' %}
 264
 265 The arvados-git-httpd package includes configuration files for systemd.  If you're using a different init system, you'll need to configure a service to start and stop an @arvados-git-httpd@ process as desired.
 266
 267 {% include 'notebox_end' %}
 268
 269 Create the configuration file @/etc/arvados/git-httpd/git-httpd.yml@. Run @arvados-git-httpd -h@ to learn more about configuration entries.
 270
 271 <notextile>
 272 <pre><code>Client:
 273   APIHost: <b>uuid_prefix.your.domain</b>
 274   Insecure: false
 275 GitCommand: /var/lib/arvados/git/gitolite/src/gitolite-shell
 276 GitoliteHome: /var/lib/arvados/git
 277 Listen: :9001
 278 RepoRoot: /var/lib/arvados/git/repositories
 279 </code></pre>
 280 </notextile>
 281
 282 Restart the systemd service to ensure the new configuration is used.
 283
 284 <notextile>
 285 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-git-httpd</span>
 286 </code></pre>
 287 </notextile>
 288
 289 h3. Set up a reverse proxy to provide SSL service
 290
 291 The arvados-git-httpd service will be accessible from anywhere on the internet, so we recommend using SSL.
 292
 293 This is best achieved by putting a reverse proxy with SSL support in front of arvados-git-httpd, running on port 443 and passing requests to @arvados-git-httpd@ on port 9001 (or whichever port you used in your run script).
 294
 295 Add the following configuration to the @http@ section of your Nginx configuration:
 296
 297 <notextile>
 298 <pre><code>
 299 upstream arvados-git-httpd {
 300   server                  127.0.0.1:<span class="userinput">9001</span>;
 301 }
 302 server {
 303   listen                  <span class="userinput">[your public IP address]</span>:443 ssl;
 304   server_name             git.<span class="userinput">uuid_prefix.your.domain</span>;
 305   proxy_connect_timeout   90s;
 306   proxy_read_timeout      300s;
 307
 308   ssl on;
 309   ssl_certificate         <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
 310   ssl_certificate_key     <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
 311
 312   # The server needs to accept potentially large refpacks from push clients.
 313   client_max_body_size 50m;
 314
 315   location  / {
 316     proxy_pass            http://arvados-git-httpd;
 317   }
 318 }
 319 </code></pre>
 320 </notextile>
 321
 322 h3. Configure the API server to advertise the correct HTTPS URLs
 323
 324 In your API server's @application.yml@ file, add the following entry:
 325
 326 <notextile>
 327 <pre><code>git_repo_https_base: https://git.<span class="userinput">uuid_prefix.your.domain</span>/
 328 </code></pre>
 329 </notextile>
 330
 331 Make sure to include the trailing slash.
 332
 333 h2. Restart Nginx
 334
 335 Restart Nginx to make the Nginx and API server configuration changes take effect.
 336
 337 <notextile>
 338 <pre><code>gitserver:~$ <span class="userinput">sudo nginx -s reload</span>
 339 </code></pre>
 340 </notextile>