misc

[gitolite-doc.git] / install.mkd

<!-- options: toc -->

% install and setup

include sidebar-toc

@@box-r(**NOTE**: this page is about an ssh mode installation.  There's a
different page for [http mode][http] installation if you need that.)@@

This page talks about installing the software and setting it up.  The install
step gets the code to where you want it.  The setup step creates the files and
directories gitolite needs, including the special gitolite-admin repo, and
makes you an administrator so you can manage it remotely.

@@red(**NOTE** on package manager installs)@@: make sure you get gitolite
**v3.x**.  The correct package you want may be called "gitolite3", even though
"gitolite" also exists.  If you want to know what the latest gitolite version
is, the gitolite [CHANGELOG][cl] will tell you.

[cl]: https://github.com/sitaramc/gitolite/blob/master/CHANGELOG

@@red(**NOTE** on upgrades from v1 or v2)@@: upgrading from v1 or v2 is
reasonably easy, but, sadly, cannot be automated.  Instructions are
[here][migr].

# quick install+setup for experts {#qi}

If your Unix-fu and ssh-fu are good, just copy your ssh public key (i.e., the
`~/.ssh/id_rsa.pub` file) from your workstation to the hosting user, then do
something like this:

    su - git
    mkdir -p ~/bin

    git clone git://github.com/sitaramc/gitolite
    gitolite/install -ln ~/bin          # please use absolute path here
    gitolite setup -pk yourname.pub

Please be sure to read any messages produced by these steps, especially the
last one, to make sure things went OK.

Notes:

1.  If your hosting user is not 'git', substitute accordingly.
2.  Make sure `~/bin` is in `$PATH`.  If it is not, add something to your
    shell startup files to make it so.  If some other writable directory is in
    the path, you can use that if you like.
3.  Substitute your name for "yourname" :-)

# the scenic route

Please DO read the [concepts and terminology][concepts] page before going
further.

## (a graphical overview)

Here's a graphical overview of what files/directories are affected by each
step in the install+setup process.  Alice is installing gitolite, with herself
as the administrator.

.aa in-1.png

/-----------------\    /----------------------\
|  user "alice"   |    |     user "git"       |
|(on workstation) |    |     (on server)      |
|cPNK             |    |cGRE                  |
\-----------------/    \----------------------/
/-----------------\    /----------------------\
|~/.ssh/id_rsa.pub|--->|      alice.pub       |-----\
\----------+------/(1) \----------------------/     |
                       /----------------------\     |
           /---------->|     ~/gitolite       |-----+
           | (2) /-----|                      |     |
           |     |     \----------------------/     |
           |     |     /----------------------\     |
           |     |     |        ~/bin         |-----+
           |     \---->|                      |     |
           |       (3) \----------------------/     |
/----------+----\      /----------------------\     |
|    (github)   |      |    ~/.gitolite.rc    |     |
|cBLU           |      |~/.ssh/authorized_keys|<----/
\---------------/      |     ~/.gitolite      | (4)
                       |    ~/repositories    |
                       \----------------------/

.end

![](in-1.png)

The files names you see there are **only for information**.  You do **not**
have to do anything to them yourself; in fact you should not!  You only need
the command for each step shown:

1.  Copy the admin's pubkey to the server as "alice.pub".
2.  Run `git clone git://github.com/sitaramc/gitolite` or equivalent.
3.  Run `gitolite/install -ln`.
4.  Run `gitolite setup -pk alice.pub`.

Note also that you only need ONE real user on the server.  In our example it
is git.  In particular, you do NOT create Unix userids for your gitolite
users.

## prepare for the install

The simplest, most foolproof, way of ensuring that your gitolite install +
setup will succeed is to use a brand new userid as the hosting user.  If that
is not possible, make sure the following do NOT exist in that user's home
directory: `~/.gitolite.rc`, `~/.gitolite`, `~/repositories`, and
`~/.ssh/authorized_keys`.

@@red(Before you go trashing that authorized keys file, please make sure you
know the password to the 'git' user, or know the root password on the
machine!)@@

@@gray(The authorized keys file *can* exist, actually, as long as none of the
keys you intend to use with gitolite are present in it.  But again, if you're
not an ssh guru, you should probably play safe.)@@

## get the software

Get the software using git-clone:

    git clone git://github.com/sitaramc/gitolite

You can use this as is, or you can check out the latest tag to make sure
you're running a tagged version instead of just the current 'master'.

## install

Gitolite has one server side command: `gitolite`.  You don't need to place it
anywhere special; in the worst case you can run it with the full path.

"Installation" consists deciding where to put it:

1.  Keep the sources anywhere and use the full path to run the `gitolite`
    command.
2.  Keep the sources anywhere and symlink *just* the `gitolite` program to
    some directory on your `$PATH`.
3.  Copy the sources somewhere and use that path to run the `gitolite`
    command.

Option 2 is the best for general use, but here's the scoop on all of them:

    # option 1
    gitolite/install

    # option 2
    gitolite/install -ln
    # defaults to $HOME/bin (which is assumed to exist)
    #   ** or **
    # or use a specific directory (please supply FULL path):
    gitolite/install -ln /usr/local/bin

    # option 3
    # (again, please supply a FULL path)
    gitolite/install -to /usr/local/gitolite/bin

Creating a symlink doesn't need a separate program but 'install' also runs
`git describe` to create a VERSION file, which can be very important if you
want support :-)

## setup {#setup}

For the first-time setup, you need to have a public key file (usually from
the admin's workstation) ready.  If the main gitolite admin's username is
"alice", this file should be named "alice.pub" and copied to the server.

Once that is done, run:

    gitolite setup -pk alice.pub

If that completes without any warnings, you are done.  If it had a warning,
you probably supplied a key which already has shell access to the server.
That won't work; you'll have to generate and use a different key pair for
gitolite access and use [host aliases][ssh-ha] to distinguish between the two.
While you're there, read both the [ssh][] pages.  Twice.

----

The 'setup' command has other uses, so you will be running it at other times
after the install as well:

  * To setup the update hook when you move [existing][] repos to gitolite.
    This also applies if someone has been fiddling with the hooks on some
    repos and you want to put them all right quickly.

  * To replace a [lost admin key][lost-key].

  * To setup gitolite for http mode (run 'gitolite setup -h' for more info).

When in doubt, run 'gitolite setup' anyway; it doesn't do any harm, though it
may take a minute or so if you have more than a few thousand repos!

# upgrading {#upgrading}

  * Update your clone of the gitolite source.
  * Repeat the install command you used earlier (make sure you use the same
    arguments as before).
  * Run `gitolite setup`.

# appendix 1: moving servers {#moving}

<!-- XXX TODO: maybe a nice picture? -->

@@box-r(Note: This section has one or more [forward references][fr].)@@

Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
any repository except the gitolite-admin repo.  The only thing it will
normally touch is the `update` hook.  So one fool-proof way of "moving"
servers is this (XXX TODO XXX -- test this and remove the next phrase)
untested but should work; feedback appreciated):

1.  Clone the latest gitolite-admin repo from the old server to your
    workstation.  Make sure you have an admin key that has RW+ rights to the
    gitolite-admin repo; you will need this later.

2.  Install gitolite on the new server, using the same key for the admin as
    for the old server.

3.  Copy the [rc][] file from the old server, overwriting this one.

4.  [Disable][writable] the old server so people won't push to it.

5.  Copy all the repos over from the old server.  Make sure the files end up
    with the right ownership and permissions; if not, chown/chmod them.

    The gitolite-admin repo already exists on the new server (it's just a bare
    bones conf file).  Do NOT overwrite it.  (Not because it contains anything
    useful, but because the next step will then fail!)

6.  Go to the clone you made in step 1, add a new remote (or change an
    existing one) to point to the new server, then `git push -f` to it.

7.  Run `gitolite setup`.