</code></pre>
</notextile>
+{% include 'install_git' %}
+
h2. Create a "git" user and a storage directory
-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@.
+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@.
A new UNIX account called "git" will own the files. This makes git URLs look familiar to users (<code>git@[...]:username/reponame.git</code>).
</code></pre>
</notextile>
-The git user needs its own SSH key. (It must be able to run @ssh git@localhost@ from scripts.)
+The git user needs its own SSH key. (It must be able to run <code>ssh git@localhost</code> from scripts.)
<notextile>
<pre><code>gitserver:~$ <span class="userinput">sudo -u git -i bash</span>
h2. Install gitolite
-Check https://github.com/sitaramc/gitolite/tags for the latest stable version (_e.g.,_ @v3.6.3@).
+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.3@. _Versions below 3.0 are missing some features needed by Arvados, and should not be used._
Download and install the version you selected.
</code></pre>
</notextile>
+_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/._
+
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.
<notextile>
</code></pre>
</notextile>
-h2. Configure gitolite
+h3. Configure gitolite
Configure gitolite to look up a repository name like @username/reponame.git@ and find the appropriate bare repository storage directory.
</span></code></pre>
</notextile>
+Inside that section, adjust the 'UMASK' setting to @022@, to ensure the API server has permission to read repositories:
+
+<notextile>
+<pre><code> UMASK => <span class="userinput">022</span>,
+</code></pre>
+</notextile>
+
Uncomment the 'Alias' line in the section that begins @ENABLE => [@:
<notextile>
</code></pre>
</notextile>
-h2. Enable the synchronization script
+h3. Enable the synchronization script
-The API server package includes a script that retrieves the current set of repository names and permissions from the API, writes names and permissions to @arvadosaliases.pl@ in a format usable by gitolite, and creates new empty repositories if needed. This script should run every 2 to 5 minutes.
+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.
If you are using RVM, create @/etc/cron.d/arvados-git-sync@ with the following content:
</code></pre>
</notextile>
+h3. Configure the API server to advertise the correct SSH URLs
+
+In your API server's @application.yml@ file, add the following entry:
+
+<notextile>
+<pre><code>git_repo_ssh_base: "git@git.<span class="userinput">uuid_prefix.your.domain</span>:"
+</code></pre>
+</notextile>
+
+Make sure to include the trailing colon.
+
h2. Install the arvados-git-httpd package
This is needed only for HTTPS access.
h3. Enable arvados-git-httpd
-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.
+On Debian-based systems, install runit:
<notextile>
<pre><code>~$ <span class="userinput">sudo apt-get install runit</span>
-~$ <span class="userinput">cd /etc/sv</span>
+</code></pre>
+</notextile>
+
+On Red Hat-based systems, "install runit from source":http://smarden.org/runit/install.html or use an alternative daemon supervisor.
+
+Configure runit to run arvados-git-httpd, making sure to update the API host to match your site:
+
+<notextile>
+<pre><code>~$ <span class="userinput">cd /etc/sv</span>
/etc/sv$ <span class="userinput">sudo mkdir arvados-git-httpd; cd arvados-git-httpd</span>
/etc/sv/arvados-git-httpd$ <span class="userinput">sudo mkdir log</span>
/etc/sv/arvados-git-httpd$ <span class="userinput">sudo sh -c 'cat >log/run' <<'EOF'
</code></pre>
</notextile>
+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:
+
+<notextile>
+<pre><code>sudo -u git \
+ ARVADOS_API_HOST=<span class="userinput">uuid_prefix.your.domain</span> \
+ GITOLITE_HTTP_HOME=/var/lib/arvados/git \
+ PATH="$PATH:/var/lib/arvados/git/bin" \
+ arvados-git-httpd -address=:9001 -git-command="$(which git)" -repo-root=<span class="userinput">/var/lib/arvados/git/repositories</span> 2>&1
+</code></pre>
+</notextile>
+
h3. Set up a reverse proxy to provide SSL service
The arvados-git-httpd service will be accessible from anywhere on the internet, so we recommend using SSL.
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).
+Add the following configuration to the @http@ section of your Nginx configuration:
+
<notextile>
-<pre><code><span class="userinput">http {
- upstream arvados-git-httpd {
- server localhost:9001;
- }
- server {
- listen *:443 ssl;
- server_name git.uuid_prefix.example.com;
- ssl_certificate /root/git.uuid_prefix.example.com.crt;
- ssl_certificate_key /root/git.uuid_prefix.example.com.key;
- location / {
- proxy_pass http://arvados-git-httpd;
- proxy_set_header X-Forwarded-For $remote_addr;
- }
+<pre><code>
+upstream arvados-git-httpd {
+ server 127.0.0.1:<span class="userinput">9001</span>;
+}
+server {
+ listen <span class="userinput">[your public IP address]</span>:443 ssl;
+ server_name git.<span class="userinput">uuid_prefix.your.domain</span>;
+ proxy_connect_timeout 90s;
+ proxy_read_timeout 300s;
+
+ ssl on;
+ ssl_certificate <span class="userinput">/YOUR/PATH/TO/cert.pem</span>;
+ ssl_certificate_key <span class="userinput">/YOUR/PATH/TO/cert.key</span>;
+
+ location / {
+ proxy_pass http://arvados-git-httpd;
}
}
-</span>
</code></pre>
</notextile>
-h3. Tell the API server about the arvados-git-httpd service
+h3. Configure the API server to advertise the correct HTTPS URLs
+
+In your API server's @application.yml@ file, add the following entry:
+
+<notextile>
+<pre><code>git_repo_http_base: https://git.<span class="userinput">uuid_prefix.your.domain</span>/
+</code></pre>
+</notextile>
+
+Make sure to include the trailing slash.
+
+h2. Restart Nginx
-In your API server's @config/application.yml@ file, add the following entry:
+Restart Nginx to make the Nginx and API server configuration changes take effect.
<notextile>
-<pre><code>git_http_base: git.<span class="userinput">uuid_prefix.your.domain</span>
+<pre><code>gitserver:~$ <span class="userinput">sudo nginx -s reload</span>
</code></pre>
</notextile>