mirror of
https://github.com/wahyd4/gitolite.git
synced 2026-08-16 16:35:58 +10:00
252 lines
11 KiB
HTML
252 lines
11 KiB
HTML
<head>
|
|
<title>
|
|
gitolite installation
|
|
</title>
|
|
<style>
|
|
body { background: #fff; margin-left: 40px; font-size: 0.9em; font-family: sans-serif; max-width: 800px; }
|
|
h1 { background: #ffb; margin-left: -30px; border-top: 5px solid #ccc; }
|
|
h2 { background: #ffb; margin-left: -20px; border-top: 3px solid #ddd; }
|
|
h3 { background: #ffb; margin-left: -10px; }
|
|
h4 { background: #ffb; }
|
|
code { font-size: 1.1em; background: #ddf; }
|
|
pre { margin-left: 2em; background: #ddf; }
|
|
pre code { font-size: 1.1em; background: #ddf; }
|
|
</style>
|
|
|
|
</head>
|
|
|
|
<p style="text-align:center">
|
|
<a href="master-toc.html">master TOC</a>
|
|
|
|
|
<a href="master-toc.html#install">chapter TOC</a>
|
|
|
|
|
<a href="support.html">support</a>
|
|
</p>
|
|
|
|
|
|
<h1>gitolite installation</h1>
|
|
|
|
<p>(Note: git servers are most commonly used with ssh URLs, and this document
|
|
describes installing gitolite to support such usage. If your users prefer
|
|
http URLs, read <a href="http.html" title="how to setup gitolite to use smart http mode">this</a> to install gitolite to support "smart http").</p>
|
|
|
|
<p><a name="install_installing_and_upgrading_gitolite_"></a></p>
|
|
|
|
<h2>installing and upgrading gitolite</h2>
|
|
|
|
<p>This section tells you how to install/upgrade gitolite, without too much
|
|
background. Later sections have more details and troubleshooting info; please
|
|
read them before asking for help if you have problems.</p>
|
|
|
|
<p>A bare minimum gitolite setup has:</p>
|
|
|
|
<ul>
|
|
<li>a server</li>
|
|
<li>a "hosting user" on the server (a real Unix userid; we use "git" in this
|
|
document, although RPM/DEB installs use "gitolite")</li>
|
|
<li>a virtual "admin user" -- the user who sets up gitolite and configures it</li>
|
|
<li>the admin user's client or workstation, from which he does all his work</li>
|
|
</ul>
|
|
|
|
<p>Gitolite allows 3 methods of install. The two most common are (1) the
|
|
<strong>package method</strong>, used if you have a gitolite RPM or a DEB available, and
|
|
(2) the <strong>non-root method</strong> which is the preferred manual install mode. Less
|
|
commonly used is (3) the <strong>root method</strong>, which is useful if you plan to have
|
|
multiple "hosting users" on the same server.</p>
|
|
|
|
<p>These install methods are described in detail below. (<em>Once you finish the
|
|
install, read the <a href="admin.html" title="administering and running gitolite">admin document</a> to administer your gitolite
|
|
installation</em>).</p>
|
|
|
|
<h3>package method: <a href="rpmdeb.html" title="package method">Link</a></h3>
|
|
|
|
|
|
<h3>non-root method: <a href="nonroot.html" title="non-root method">Link</a></h3>
|
|
|
|
|
|
<h3>root method: <a href="root.html" title="root method">Link</a></h3>
|
|
|
|
|
|
<p><a name="upgrade"></a></p>
|
|
|
|
<h3>upgrading</h3>
|
|
|
|
<p>Upgrading is easy; you just re-run some of the same commands used for install.
|
|
These commands are clearly noted in the install instructions above.</p>
|
|
|
|
<p>However, if you've added any new hooks, you must also run the next step (the
|
|
<code>gl-setup</code> command), although this time you don't need to supply a pubkey
|
|
filename as an argument.</p>
|
|
|
|
<p><a name="insttrouble"></a></p>
|
|
|
|
<h2>install trouble?</h2>
|
|
|
|
<p>If you run into trouble, please read the following sections.</p>
|
|
|
|
<p><a name="install_common_install_problems_"></a></p>
|
|
|
|
<h3>common install problems</h3>
|
|
|
|
<p>The most common problem is usually ssh. Here are three facts of ssh:</p>
|
|
|
|
<ul>
|
|
<li>ssh is a pain</li>
|
|
<li>most people don't know ssh well enough</li>
|
|
<li>even people who think they do, don't</li>
|
|
</ul>
|
|
|
|
<p>Please read how <a href="gl_ssh.html" title="how gitolite uses ssh">gitolite uses ssh</a> and the <a href="sts.html" title="ssh troubleshooting">ssh
|
|
troubleshooting</a> documents before asking for help.</p>
|
|
|
|
<p>If you've tried multiple methods of install, you may have multiple copies of
|
|
the sources lying around. This could be a problem; see <a href="install.html#instpath" title="appendix a: PATH issues for gl-setup">appendix a</a>
|
|
for how to detect and deal with this.</p>
|
|
|
|
<p>If none of this works read the rest of this document, understand it as much as
|
|
you can, then ask for help.</p>
|
|
|
|
<p><a name="instnameconv"></a></p>
|
|
|
|
<h3>naming conventions used</h3>
|
|
|
|
<p>Throughout the documentation, we use "YourName" as the admin user, and his
|
|
workstation is called "client". The hosting user is "git", and the server is
|
|
called "server". <strong>Please substitute your values as needed</strong>.</p>
|
|
|
|
<p><strong>If you're using DEB or RPM</strong>, the installer creates a user called
|
|
"gitolite", so substitute that for "git" anywhere in the docs where the
|
|
"hosting user" is mentioned as "git".</p>
|
|
|
|
<p>Also, we often say "the rc file". This means <code>~/.gitolite.rc</code> on the server.
|
|
And when we say the "access control rules", or "conf file", or "config file",
|
|
we mean <code>conf/gitolite.conf</code> on your gitolite-admin clone.</p>
|
|
|
|
<h3>helpful background information: <a href="instbg.html" title="helpful background information">Link</a></h3>
|
|
|
|
|
|
<h3>requirements: <a href="instrequire.html" title="requirements">Link</a></h3>
|
|
|
|
|
|
<h3>getting the gitolite software: <a href="getgl_.html" title="getting the gitolite software">Link</a></h3>
|
|
|
|
|
|
<p><a name="instappendices_"></a></p>
|
|
|
|
<h2>appendixes</h2>
|
|
|
|
<p>The following sections have some miscellaneous information that does not
|
|
cleanly to fit anywhere else.</p>
|
|
|
|
<p><a name="instpath"></a></p>
|
|
|
|
<h3>appendix a: PATH issues for gl-setup</h3>
|
|
|
|
<p>If you've tried multiple methods of install, you may have multiple copies of
|
|
the sources lying around, and when you ran <code>gl-setup</code> it picked up the wrong
|
|
one. This might also happen if the directory you supplied as the first
|
|
argument to <code>gitolite/src/gl-system-install</code> is not even in the <code>$PATH</code>.</p>
|
|
|
|
<p>Run <code>su - git</code> then <code>which gl-setup</code> to see which it picked up. This is what
|
|
it should be for each method:</p>
|
|
|
|
<ul>
|
|
<li>RPM/DEB method: probably <code>/usr/bin</code></li>
|
|
<li>root method: the first argument to the <code>gitolite/src/gl-system-install</code> command (or
|
|
<code>/usr/local/bin</code> by default)</li>
|
|
<li>non-root method: the first argument to the <code>gitolite/src/gl-system-install</code> command
|
|
(or <code>$HOME/bin</code> by default)</li>
|
|
</ul>
|
|
|
|
<p>If this is not what you get, remove the partially installed or extraneous
|
|
sources, if any, and try again. Or fix your <code>$PATH</code>.</p>
|
|
|
|
<p>One situation that is not easy to solve is if the system admin installed
|
|
gitolite using the RPM/DEB or root methods, and you want to install a later
|
|
version using the non-root method. Since <code>/usr/bin</code> and <code>/usr/local/bin</code> are
|
|
usually earlier than <code>$HOME/bin</code> in the <code>$PATH</code>, you'll have to get creative.
|
|
Good luck.</p>
|
|
|
|
<p><a name="clean"></a></p>
|
|
|
|
<h3>appendix b: cleaning out a botched install</h3>
|
|
|
|
<p>When people have trouble installing gitolite, they often try to change a bunch
|
|
of things manually on the server. Or sometimes they'll upgrade from one
|
|
install method to another without checking some things over properly. Or
|
|
they'll follow instructions meant for a much newer version of gitolite and
|
|
make a royal mess of the whole thing.</p>
|
|
|
|
<p>Here's how to clean up, without losing your actual repositories.</p>
|
|
|
|
<p>All this is on the server. Note that the instructions are so long because
|
|
they're generic enough to fit any situation.</p>
|
|
|
|
<ul>
|
|
<li><p>Clean out the existing install</p>
|
|
|
|
<ul>
|
|
<li><p>edit <code>~/.ssh/authorized_keys</code> and delete all lines between <code># gitolite
|
|
start</code> and <code># gitolite end</code> inclusive.</p></li>
|
|
<li><p>look in <code>~/.gitolite.rc</code> for 2 variables starting with <code>GL_PACKAGE_</code>.
|
|
If they are defined (and not just commented out), you need to clean
|
|
out all gitolite related files and directories from those two paths.</p>
|
|
|
|
<p>Just for reference, the defaults for a non-root install are 'conf' and
|
|
'hooks' in <code>$HOME/share/gitolite</code>, while for an RPM/DEB or root
|
|
install they should be in <code>/var/gitolite/</code> or some such.</p>
|
|
|
|
<p>If those variables don't exist or are commented out, ignore this step.</p></li>
|
|
<li><p>look in <code>$PATH</code> for any gitolite programs and delete them also. A
|
|
good way to hunt them down is <code>which gl-auth-command</code>, and in the path
|
|
you find, delete all "gl-*" programs (perhaps after checking the list,
|
|
if the path you find happens to be /usr/bin or such!!)</p>
|
|
|
|
<p>Repeat this step until there are no more. I know of people who mixed
|
|
different install methods and had two, or even three, versions lying
|
|
around.</p></li>
|
|
<li><p>make some temp directory (say "old"), and <strong>move</strong> the following
|
|
files/directories into it: <code>~/.gitolite</code>, <code>~/.gitolite.rc</code> and
|
|
<code>~/repositories/gitolite-admin.git</code>. If there's nothing you need to
|
|
salvage from them you can delete them too.</p></li>
|
|
<li><p>if you used an RPM/DEB install, remove the package also.</p></li>
|
|
</ul></li>
|
|
<li><p>Now install a fresh copy of gitolite using whatever method you prefer.
|
|
(If you used a different method earlier and did not clean things out
|
|
properly per the instructions given above, expect trouble).</p></li>
|
|
<li><p>You now have a brand new "rc" file. If your old rc file had any
|
|
non-default settings you should <strong>manually</strong> pull them in to the new one.
|
|
However, <strong>do NOT</strong> change the two variables starting with <code>GL_PACKAGE_</code>
|
|
in the new rc file; even if the old one had something different leave them
|
|
alone.</p></li>
|
|
<li><p>You also have a brand new gitolite-admin repo. Clone this to your
|
|
workstation, then use the saved copy of the old admin repo to salvage
|
|
whatever you need (entire revision history, or just the conf/key files,
|
|
whatever floats your boat).</p>
|
|
|
|
<p>Once you've got your admin repo looking how you want it, including 'repo'
|
|
statements for all your existing repos, just add/commit/push it.</p></li>
|
|
<li><p>Go back to the server and run <code>gl-setup</code> once again (no arguments needed).</p></li>
|
|
</ul>
|
|
|
|
<p>That should do it.</p>
|
|
|
|
<p><a name="uninstall_"></a></p>
|
|
|
|
<h3>appendix c: uninstalling gitolite completely</h3>
|
|
|
|
<p>To uninstall gitolite completely, first follow the "clean out..." steps in the
|
|
previous section.</p>
|
|
|
|
<p>If you have not really started using gitolite properly yet, you can remove all
|
|
of <code>~/repositories</code> also and be done.</p>
|
|
|
|
<p>But if you <em>do</em> need to preserve the other repos and wish to continue to use
|
|
them, remove all the <code>update</code> hooks that gitolite installs in each repository.
|
|
The easiest way is:</p>
|
|
|
|
<pre><code>find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
|
|
</code></pre>
|
|
|
|
<p>but you can do it manually if you want to be careful.</p>
|