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 On the API server, if you are using RVM:
  38
  39 <notextile>
  40 <pre><code>gitserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  41 gitserver:/var/www/arvados-api/current$ <span class="userinput">sudo -u www-data RAILS_ENV=production `which rvm-exec` default bundle exec ./script/create_superuser_token.rb</span>
  42 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  43 </code></pre>
  44 </notextile>
  45
  46 If you are not using RVM:
  47
  48 <notextile>
  49 <pre><code>gitserver:~$ <span class="userinput">cd /var/www/arvados-api/current</span>
  50 gitserver:/var/www/arvados-api/current$ <span class="userinput">sudo -u www-data RAILS_ENV=production bundle exec ./script/create_superuser_token.rb</span>
  51 zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz
  52 </code></pre>
  53 </notextile>
  54
  55 Copy that token; you'll need it in a minute.
  56
  57 h2. Install git and other dependencies
  58
  59 On Debian-based systems:
  60
  61 <notextile>
  62 <pre><code>gitserver:~$ <span class="userinput">sudo apt-get install git openssh-server</span>
  63 </code></pre>
  64 </notextile>
  65
  66 On Red Hat-based systems:
  67
  68 <notextile>
  69 <pre><code>gitserver:~$ <span class="userinput">sudo yum install git perl-Data-Dumper openssh-server</span>
  70 </code></pre>
  71 </notextile>
  72
  73 h2. Create a "git" user and a storage directory
  74
  75 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 @config/application.yml@ file accordingly: for example, if you install gitolite at @/data/gitolite@ then your @git_repositories_dir@ will be @/data/gitolite/repositories@.
  76
  77 A new UNIX account called "git" will own the files. This makes git URLs look familiar to users (<code>git@[...]:username/reponame.git</code>).
  78
  79 On Debian- or Red Hat-based systems:
  80
  81 <notextile>
  82 <pre><code>gitserver:~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
  83 gitserver:~$ <span class="userinput">sudo useradd --comment git --home-dir /var/lib/arvados/git git</span>
  84 gitserver:~$ <span class="userinput">sudo chown -R git:git ~git</span>
  85 </code></pre>
  86 </notextile>
  87
  88 The git user needs its own SSH key. (It must be able to run @ssh git@localhost@ from scripts.)
  89
  90 <notextile>
  91 <pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
  92 git@gitserver:~$ <span class="userinput">ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa</span>
  93 git@gitserver:~$ <span class="userinput">cp .ssh/id_rsa.pub .ssh/authorized_keys</span>
  94 git@gitserver:~$ <span class="userinput">ssh -o stricthostkeychecking=no localhost cat .ssh/id_rsa.pub</span>
  95 Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
  96 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver
  97 git@gitserver:~$ <span class="userinput">rm .ssh/authorized_keys</span>
  98 </code></pre>
  99 </notextile>
 100
 101 h2. Install gitolite
 102
 103 Check https://github.com/sitaramc/gitolite/tags for the latest stable version (_e.g.,_ @v3.6.3@).
 104
 105 Download and install the version you selected.
 106
 107 <notextile>
 108 <pre><code>git@gitserver:~$ <span class="userinput">echo 'PATH=$HOME/bin:$PATH' &gt;.profile</span>
 109 git@gitserver:~$ <span class="userinput">source .profile</span>
 110 git@gitserver:~$ <span class="userinput">git clone --branch <b>v3.6.3</b> git://github.com/sitaramc/gitolite</span>
 111 ...
 112 Note: checking out '5d24ae666bfd2fa9093d67c840eb8d686992083f'.
 113 ...
 114 git@gitserver:~$ <span class="userinput">mkdir bin</span>
 115 git@gitserver:~$ <span class="userinput">gitolite/install -ln ~git/bin</span>
 116 git@gitserver:~$ <span class="userinput">bin/gitolite setup -pk .ssh/id_rsa.pub</span>
 117 Initialized empty Git repository in /var/lib/arvados/git/repositories/gitolite-admin.git/
 118 Initialized empty Git repository in /var/lib/arvados/git/repositories/testing.git/
 119 WARNING: /var/lib/arvados/git/.ssh/authorized_keys missing; creating a new one
 120     (this is normal on a brand new install)
 121 </code></pre>
 122 </notextile>
 123
 124 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.
 125
 126 <notextile>
 127 <pre><code>git@gitserver:~$ <span class="userinput">git clone git@localhost:gitolite-admin</span>
 128 Cloning into 'gitolite-admin'...
 129 remote: Counting objects: 6, done.
 130 remote: Compressing objects: 100% (4/4), done.
 131 remote: Total 6 (delta 0), reused 0 (delta 0)
 132 Receiving objects: 100% (6/6), done.
 133 Checking connectivity... done.
 134 git@gitserver:~$ <span class="userinput">cd gitolite-admin</span>
 135 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.email arvados</span>
 136 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.name arvados</span>
 137 git@gitserver:~/gitolite-admin$ <span class="userinput">git config push.default simple</span>
 138 git@gitserver:~/gitolite-admin$ <span class="userinput">git push</span>
 139 Everything up-to-date
 140 </code></pre>
 141 </notextile>
 142
 143 h2. Configure gitolite
 144
 145 Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
 146
 147 Add the following lines to the top of @~git/.gitolite.rc@:
 148
 149 <notextile>
 150 <pre><code><span class="userinput">my $repo_aliases;
 151 my $aliases_src = "$ENV{HOME}/.gitolite/arvadosaliases.pl";
 152 if ($ENV{HOME} && (-e $aliases_src)) {
 153     $repo_aliases = do $aliases_src;
 154 }
 155 $repo_aliases ||= {};
 156 </span></code></pre>
 157 </notextile>
 158
 159 Add the following lines inside the section that begins @%RC = (@:
 160
 161 <notextile>
 162 <pre><code><span class="userinput">    REPO_ALIASES => $repo_aliases,
 163 </span></code></pre>
 164 </notextile>
 165
 166 Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
 167
 168 <notextile>
 169 <pre><code><span class="userinput">            # access a repo by another (possibly legacy) name
 170             'Alias',
 171 </span></code></pre>
 172 </notextile>
 173
 174 h2. Configure git synchronization
 175
 176 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.
 177 * For @arvados_api_token@, use the token you generated above.
 178 * For @gitolite_arvados_git_user_key@, provide the public key you generated above, i.e., the contents of @~git/.ssh/id_rsa.pub@.
 179
 180 <notextile>
 181 <pre><code>production:
 182   gitolite_url: /var/lib/arvados/git/repositories/gitolite-admin.git
 183   gitolite_tmp: /var/lib/arvados/git
 184   arvados_api_host: <span class="userinput">uuid_prefix.example.com</span>
 185   arvados_api_token: "<span class="userinput">zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>"
 186   arvados_api_host_insecure: <span class="userinput">false</span>
 187   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>"
 188 </code></pre>
 189 </notextile>
 190
 191 h2. Enable the synchronization script
 192
 193 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.
 194
 195 If you are using RVM, create @/etc/cron.d/arvados-git-sync@ with the following content:
 196
 197 <notextile>
 198 <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>
 199 </code></pre>
 200 </notextile>
 201
 202 Otherwise, create @/etc/cron.d/arvados-git-sync@ with the following content:
 203
 204 <notextile>
 205 <pre><code><span class="userinput">*/5 * * * * git cd /var/www/arvados-api/current && bundle exec script/arvados-git-sync.rb production</span>
 206 </code></pre>
 207 </notextile>
 208
 209 h3. Configure the API server to advertise the correct SSH URLs
 210
 211 In your API server's @config/application.yml@ file, add the following entry:
 212
 213 <notextile>
 214 <pre><code>git_repo_ssh_base: git@git.<span class="userinput">uuid_prefix.your.domain</span>:
 215 </code></pre>
 216 </notextile>
 217
 218 Make sure to include the trailing colon.
 219
 220 h2. Install the arvados-git-httpd package
 221
 222 This is needed only for HTTPS access.
 223
 224 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.
 225
 226 On Debian-based systems:
 227
 228 <notextile>
 229 <pre><code>~$ <span class="userinput">sudo apt-get install git arvados-git-httpd</span>
 230 </code></pre>
 231 </notextile>
 232
 233 On Red Hat-based systems:
 234
 235 <notextile>
 236 <pre><code>~$ <span class="userinput">sudo yum install git arvados-git-httpd</span>
 237 </code></pre>
 238 </notextile>
 239
 240 Verify that @arvados-git-httpd@ and @git-http-backend@ can be run:
 241
 242 <notextile>
 243 <pre><code>~$ <span class="userinput">arvados-git-httpd -h</span>
 244 Usage of arvados-git-httpd:
 245   -address="0.0.0.0:80": Address to listen on, "host:port".
 246   -git-command="/usr/bin/git": Path to git executable. Each authenticated request will execute this program with a single argument, "http-backend".
 247   -repo-root="/path/to/cwd": Path to git repositories.
 248 ~$ <span class="userinput">git http-backend</span>
 249 Status: 500 Internal Server Error
 250 Expires: Fri, 01 Jan 1980 00:00:00 GMT
 251 Pragma: no-cache
 252 Cache-Control: no-cache, max-age=0, must-revalidate
 253
 254 fatal: No REQUEST_METHOD from server
 255 </code></pre>
 256 </notextile>
 257
 258 h3. Enable arvados-git-httpd
 259
 260 Install "runit":http://smarden.org/runit/ (if it's not already installed) and configure it to run arvados-git-httpd. Update the API host to match your site.
 261
 262 <notextile>
 263 <pre><code>~$ <span class="userinput">sudo apt-get install runit</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 PATH="$PATH:/var/lib/arvados/git/bin"
 278 exec chpst -u git:git arvados-git-httpd -address=:9001 -git-command="$(which git)" -repo-root=<b>/var/lib/arvados/git/repositories</b> 2&gt;&1
 279 EOF</span>
 280 /etc/sv/arvados-git-httpd$ <span class="userinput">sudo chmod +x run log/run</span>
 281 </code></pre>
 282 </notextile>
 283
 284 h3. Set up a reverse proxy to provide SSL service
 285
 286 The arvados-git-httpd service will be accessible from anywhere on the internet, so we recommend using SSL.
 287
 288 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).
 289
 290 <notextile>
 291 <pre><code><span class="userinput">http {
 292   upstream arvados-git-httpd {
 293     server localhost:9001;
 294   }
 295   server {
 296     listen *:443 ssl;
 297     server_name git.uuid_prefix.example.com;
 298     ssl_certificate /root/git.uuid_prefix.example.com.crt;
 299     ssl_certificate_key /root/git.uuid_prefix.example.com.key;
 300     location  / {
 301       proxy_pass http://arvados-git-httpd;
 302       proxy_set_header X-Forwarded-For $remote_addr;
 303     }
 304   }
 305 }
 306 </span>
 307 </code></pre>
 308 </notextile>
 309
 310 h3. Configure the API server to advertise the correct HTTPS URLs
 311
 312 In your API server's @config/application.yml@ file, add the following entry:
 313
 314 <notextile>
 315 <pre><code>git_repo_http_base: https://git.<span class="userinput">uuid_prefix.your.domain</span>/
 316 </code></pre>
 317 </notextile>
 318
 319 Make sure to include the trailing slash.