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

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