14712: Fixes default config and install doc
[arvados.git] / 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 * HTTPS is also used by Arvados Composer to access git repositories from the browser.
23
24 The HTTPS instructions given below will not work if you skip the SSH setup steps.
25
26 h2. Set up DNS
27
28 By convention, we use the following hostname for the git service:
29
30 <notextile>
31 <pre><code>git.<span class="userinput">uuid_prefix</span>.your.domain
32 </code></pre>
33 </notextile>
34
35 {% include 'notebox_begin' %}
36 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.
37 {% include 'notebox_end' %}
38
39 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.
40
41 h2. Generate an API token
42
43 {% assign railshost = "gitserver" %}
44 {% assign railscmd = "bundle exec ./script/create_superuser_token.rb" %}
45 {% assign railsout = "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" %}
46 Use the following command to generate an API token.  {% include 'install_rails_command' %}
47
48 Copy that token; you'll need it in a minute.
49
50 h2. Install git and other dependencies
51
52 On Debian-based systems:
53
54 <notextile>
55 <pre><code>gitserver:~$ <span class="userinput">sudo apt-get install git openssh-server</span>
56 </code></pre>
57 </notextile>
58
59 On Red Hat-based systems:
60
61 <notextile>
62 <pre><code>gitserver:~$ <span class="userinput">sudo yum install git perl-Data-Dumper openssh-server</span>
63 </code></pre>
64 </notextile>
65
66 {% include 'install_git' %}
67
68 h2. Create a "git" user and a storage directory
69
70 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@.
71
72 A new UNIX account called "git" will own the files. This makes git URLs look familiar to users (<code>git@[...]:username/reponame.git</code>).
73
74 On Debian- or Red Hat-based systems:
75
76 <notextile>
77 <pre><code>gitserver:~$ <span class="userinput">sudo mkdir -p /var/lib/arvados/git</span>
78 gitserver:~$ <span class="userinput">sudo useradd --comment git --home-dir /var/lib/arvados/git git</span>
79 gitserver:~$ <span class="userinput">sudo chown -R git:git ~git</span>
80 </code></pre>
81 </notextile>
82
83 The git user needs its own SSH key. (It must be able to run <code>ssh git@localhost</code> from scripts.)
84
85 <notextile>
86 <pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
87 git@gitserver:~$ <span class="userinput">ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa</span>
88 git@gitserver:~$ <span class="userinput">cp .ssh/id_rsa.pub .ssh/authorized_keys</span>
89 git@gitserver:~$ <span class="userinput">ssh -o stricthostkeychecking=no localhost cat .ssh/id_rsa.pub</span>
90 Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
91 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7aBIDAAgMQN16Pg6eHmvc+D+6TljwCGr4YGUBphSdVb25UyBCeAEgzqRiqy0IjQR2BLtSirXr+1SJAcQfBgI/jwR7FG+YIzJ4ND9JFEfcpq20FvWnMMQ6XD3y3xrZ1/h/RdBNwy4QCqjiXuxDpDB7VNP9/oeAzoATPZGhqjPfNS+RRVEQpC6BzZdsR+S838E53URguBOf9yrPwdHvosZn7VC0akeWQerHqaBIpSfDMtaM4+9s1Gdsz0iP85rtj/6U/K/XOuv2CZsuVZZ52nu3soHnEX2nx2IaXMS3L8Z+lfOXB2T6EaJgXF7Z9ME5K1tx9TSNTRcYCiKztXLNLSbp git@gitserver
92 git@gitserver:~$ <span class="userinput">rm .ssh/authorized_keys</span>
93 </code></pre>
94 </notextile>
95
96 h2. Install gitolite
97
98 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._
99
100 Download and install the version you selected.
101
102 <notextile>
103 <pre><code>git@gitserver:~$ <span class="userinput">echo 'PATH=$HOME/bin:$PATH' &gt;.profile</span>
104 git@gitserver:~$ <span class="userinput">source .profile</span>
105 git@gitserver:~$ <span class="userinput">git clone --branch <b>v3.6.4</b> https://github.com/sitaramc/gitolite</span>
106 ...
107 Note: checking out '5d24ae666bfd2fa9093d67c840eb8d686992083f'.
108 ...
109 git@gitserver:~$ <span class="userinput">mkdir bin</span>
110 git@gitserver:~$ <span class="userinput">gitolite/install -ln ~git/bin</span>
111 git@gitserver:~$ <span class="userinput">bin/gitolite setup -pk .ssh/id_rsa.pub</span>
112 Initialized empty Git repository in /var/lib/arvados/git/repositories/gitolite-admin.git/
113 Initialized empty Git repository in /var/lib/arvados/git/repositories/testing.git/
114 WARNING: /var/lib/arvados/git/.ssh/authorized_keys missing; creating a new one
115     (this is normal on a brand new install)
116 </code></pre>
117 </notextile>
118
119 _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/._
120
121 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.
122
123 <notextile>
124 <pre><code>git@gitserver:~$ <span class="userinput">git clone git@localhost:gitolite-admin</span>
125 Cloning into 'gitolite-admin'...
126 remote: Counting objects: 6, done.
127 remote: Compressing objects: 100% (4/4), done.
128 remote: Total 6 (delta 0), reused 0 (delta 0)
129 Receiving objects: 100% (6/6), done.
130 Checking connectivity... done.
131 git@gitserver:~$ <span class="userinput">cd gitolite-admin</span>
132 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.email arvados</span>
133 git@gitserver:~/gitolite-admin$ <span class="userinput">git config user.name arvados</span>
134 git@gitserver:~/gitolite-admin$ <span class="userinput">git config push.default simple</span>
135 git@gitserver:~/gitolite-admin$ <span class="userinput">git push</span>
136 Everything up-to-date
137 </code></pre>
138 </notextile>
139
140 h3. Configure gitolite
141
142 Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
143
144 Add the following lines to the top of @~git/.gitolite.rc@:
145
146 <notextile>
147 <pre><code><span class="userinput">my $repo_aliases;
148 my $aliases_src = "$ENV{HOME}/.gitolite/arvadosaliases.pl";
149 if ($ENV{HOME} && (-e $aliases_src)) {
150     $repo_aliases = do $aliases_src;
151 }
152 $repo_aliases ||= {};
153 </span></code></pre>
154 </notextile>
155
156 Add the following lines inside the section that begins @%RC = (@:
157
158 <notextile>
159 <pre><code><span class="userinput">    REPO_ALIASES => $repo_aliases,
160 </span></code></pre>
161 </notextile>
162
163 Inside that section, adjust the 'UMASK' setting to @022@, to ensure the API server has permission to read repositories:
164
165 <notextile>
166 <pre><code>    UMASK => <span class="userinput">022</span>,
167 </code></pre>
168 </notextile>
169
170 Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
171
172 <notextile>
173 <pre><code><span class="userinput">            # access a repo by another (possibly legacy) name
174             'Alias',
175 </span></code></pre>
176 </notextile>
177
178 h2. Configure git synchronization
179
180 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.
181 * For @arvados_api_token@, use the token you generated above.
182 * For @gitolite_arvados_git_user_key@, provide the public key you generated above, i.e., the contents of @~git/.ssh/id_rsa.pub@.
183
184 <notextile>
185 <pre><code>production:
186   gitolite_url: /var/lib/arvados/git/repositories/gitolite-admin.git
187   gitolite_tmp: /var/lib/arvados/git
188   arvados_api_host: <span class="userinput">uuid_prefix.example.com</span>
189   arvados_api_token: "<span class="userinput">zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz</span>"
190   arvados_api_host_insecure: <span class="userinput">false</span>
191   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>"
192 </code></pre>
193 </notextile>
194
195 h3. Enable the synchronization script
196
197 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.
198
199 If you are using RVM, create @/etc/cron.d/arvados-git-sync@ with the following content:
200
201 <notextile>
202 <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>
203 </code></pre>
204 </notextile>
205
206 Otherwise, create @/etc/cron.d/arvados-git-sync@ with the following content:
207
208 <notextile>
209 <pre><code><span class="userinput">*/5 * * * * git cd /var/www/arvados-api/current && bundle exec script/arvados-git-sync.rb production</span>
210 </code></pre>
211 </notextile>
212
213 h3. Configure the API server to advertise the correct SSH URLs
214
215 Edit the cluster config at @/etc/arvados/config.yml@ and set @Services.GitSSH.ExternalURL@. Replace @uuid_prefix@ with your cluster id.
216
217 <notextile>
218 <pre><code>Clusters:
219   <span class="userinput">uuid_prefix</span>:
220     Services:
221       GitSSH:
222         ExternalURL: <span class="userinput">git@git.uuid_prefix.your.domain:</span>
223 </code></pre>
224 </notextile>
225
226 Make sure to include the trailing colon.
227
228 h2. Install the arvados-git-httpd package
229
230 This is needed only for HTTPS access.
231
232 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.
233
234 On Debian-based systems:
235
236 <notextile>
237 <pre><code>~$ <span class="userinput">sudo apt-get install git arvados-git-httpd</span>
238 </code></pre>
239 </notextile>
240
241 On Red Hat-based systems:
242
243 <notextile>
244 <pre><code>~$ <span class="userinput">sudo yum install git arvados-git-httpd</span>
245 ~$ <span class="userinput">sudo systemctl enable arvados-git-httpd</span>
246 </code></pre>
247 </notextile>
248
249 Verify that @arvados-git-httpd@ and @git-http-backend@ can be run:
250
251 <notextile>
252 <pre><code>~$ <span class="userinput">arvados-git-httpd -h</span>
253 [...]
254 Usage: arvados-git-httpd [-config path/to/arvados/git-httpd.yml]
255 [...]
256 ~$ <span class="userinput">git http-backend</span>
257 Status: 500 Internal Server Error
258 Expires: Fri, 01 Jan 1980 00:00:00 GMT
259 Pragma: no-cache
260 Cache-Control: no-cache, max-age=0, must-revalidate
261
262 fatal: No REQUEST_METHOD from server
263 </code></pre>
264 </notextile>
265
266 h3. Enable arvados-git-httpd
267
268 {% include 'notebox_begin' %}
269
270 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.
271
272 {% include 'notebox_end' %}
273
274 Edit the cluster config at @/etc/arvados/config.yml@ and set the following values. Replace @uuid_prefix@ with your cluster id.
275
276 <notextile>
277 <pre><code>Clusters:
278   <span class="userinput">uuid_prefix</span>:
279     Services:
280       GitHTTP:
281         ExternalURL: <span class="userinput">https://git.uuid_prefix.your.domain/</span>
282         InternalURLs:
283           <span class="userinput">"http://localhost:9001": {}</span>
284     Git:
285       GitCommand: <span class="userinput">/var/lib/arvados/git/gitolite/src/gitolite-shell</span>
286       GitoliteHome: <span class="userinput">/var/lib/arvados/git</span>
287       Repositories: <span class="userinput">/var/lib/arvados/git/repositories</span>
288 </code></pre>
289 </notextile>
290
291 Make sure to include the trailing slash for @Services.GitHTTP.ExternalURL@.
292
293 Restart the systemd service to ensure the new configuration is used.
294
295
296 <notextile>
297 <pre><code>~$ <span class="userinput">sudo systemctl restart arvados-git-httpd</span>
298 </code></pre>
299 </notextile>
300
301 h3. Set up a reverse proxy to provide SSL service
302
303 The arvados-git-httpd service will be accessible from anywhere on the internet, so we recommend using SSL.
304
305 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).
306
307 Add the following configuration to the @http@ section of your Nginx configuration:
308
309 <notextile>
310 <pre><code>
311 upstream arvados-git-httpd {
312   server                  127.0.0.1:<span class="userinput">9001</span>;
313 }
314 server {
315   listen                  <span class="userinput">[your public IP address]</span>:443 ssl;
316   server_name             git.<span class="userinput">uuid_prefix.your.domain</span>;
317   proxy_connect_timeout   90s;
318   proxy_read_timeout      300s;
319
320   ssl on;
321   ssl_certificate         <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
322   ssl_certificate_key     <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
323
324   # The server needs to accept potentially large refpacks from push clients.
325   client_max_body_size 50m;
326
327   location  / {
328     proxy_pass            http://arvados-git-httpd;
329   }
330 }
331 </code></pre>
332 </notextile>
333
334 h2. Restart Nginx
335
336 Restart Nginx to make the Nginx and API server configuration changes take effect.
337
338 <notextile>
339 <pre><code>gitserver:~$ <span class="userinput">sudo nginx -s reload</span>
340 </code></pre>
341 </notextile>
342
343 h2. Clone Arvados repository
344
345 Here we create a repository object which will be used to set up a hosted clone of the arvados repository on this cluster.
346
347 <notextile>
348 <pre><code>~$ <span class="userinput">uuid_prefix=`arv --format=uuid user current | cut -d- -f1`</span>
349 ~$ <span class="userinput">echo "Site prefix is '$uuid_prefix'"</span>
350 ~$ <span class="userinput">all_users_group_uuid="$uuid_prefix-j7d0g-fffffffffffffff"</span>
351 ~$ <span class="userinput">repo_uuid=`arv --format=uuid repository create --repository "{\"owner_uuid\":\"$uuid_prefix-tpzed-000000000000000\", \"name\":\"arvados\"}"`</span>
352 ~$ <span class="userinput">echo "Arvados repository uuid is '$repo_uuid'"</span>
353 </code></pre></notextile>
354
355 Create a link object to make the repository object readable by the "All users" group, and therefore by every active user. This makes it possible for users to run the bundled Crunch scripts by specifying @"script_version":"master","repository":"arvados"@ rather than pulling the Arvados source tree into their own repositories.
356
357 <notextile>
358 <pre><code>~$ <span class="userinput">read -rd $'\000' newlink &lt;&lt;EOF; arv link create --link "$newlink"</span>
359 <span class="userinput">{
360  "tail_uuid":"$all_users_group_uuid",
361  "head_uuid":"$repo_uuid",
362  "link_class":"permission",
363  "name":"can_read"
364 }
365 EOF</span>
366 </code></pre></notextile>
367
368 In a couple of minutes, your arvados-git-sync cron job will create an empty repository on your git server. Seed it with the real arvados repository. If your git credential helpers were configured correctly when you "set up your shell server":install-shell-server.html, the "git push" command will use your API token instead of prompting you for a username and password.
369
370 <notextile>
371 <pre><code>~$ <span class="userinput">cd /tmp</span>
372 /tmp$ <span class="userinput">git clone --bare https://github.com/curoverse/arvados.git</span>
373 /tmp <span class="userinput">git --git-dir arvados.git push https://git.<b>uuid_prefix.your.domain</b>/arvados.git '*:*'</span>
374 </code></pre>
375 </notextile>
376
377 If you did not set up a HTTPS service, you can push to <code>git@git.uuid_prefix.your.domain:arvados.git</code> using your SSH key, or by logging in to your git server and using sudo.
378
379 <notextile>
380 <pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
381 git@gitserver:~$ <span class="userinput">git clone --bare https://github.com/curoverse/arvados.git /tmp/arvados.git</span>
382 git@gitserver:~$ <span class="userinput">cd /tmp/arvados.git</span>
383 git@gitserver:/tmp/arvados.git$ <span class="userinput">gitolite push /var/lib/arvados/git/repositories/<b>your_arvados_repo_uuid</b>.git '*:*'</span>
384 </code></pre>
385 </notextile>