gitolite/doc/7-install-transcript.mkd

# gitolite install transcript

This is a *complete* transcript of a full gitolite install, *from scratch*,
using brand new userids ("sita" on the client, "git" on the server).  Please
note that you can use existing userids also, it is not necessary to use
dedicated user IDs for this.  Also, you don't have to use some *other* server
for all this, both server and client can be "localhost" if you like.

Please note that this entire transcript can be summarised as:

  * create users on client and server (optional)
  * get pubkey access to server from client (`ssh-copy-id` or manual eqvt)
  * run one command ***on client*** (`gl-easy-install`)

...and only that last step is actually gitolite.  In fact, the bulk of the
transcript is **non**-gitolite stuff :)

----

### (cleaning out a botched install if needed)

When people have trouble installing gitolite, they often try to change a bunch
of things manually on the server.  This usually makes things worse ;-) so if
you're reading this document as a follow-up to a failed install, please
**first** clean out the botched install (instructions [here][appB]) and
**then** continue with this document.

[appB]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#uninstall

----

### create userids on server and client (optional)

Client side: add user, give him a password

    sita-lt:~ # useradd sita

    sita-lt:~ # passwd sita
    Changing password for user sita.
    New UNIX password:
    Retype new UNIX password:
    passwd: all authentication tokens updated successfully.

Server side: (log on to server, then) add user, give it a password

    sita-lt:~ # ssh sitaram@server
    sitaram@server's password:
    Last login: Fri Dec 18 20:25:06 2009
    -bash-3.2$ su -
    Password:

    sita-sv:~ # useradd git

    sita-sv:~ # passwd git
    Changing password for user git.
    New UNIX password:
    Retype new UNIX password:
    passwd: all authentication tokens updated successfully.

Server side: allow ssh access to "git" user

This is done by editing the sshd config file and adding "git" to the
"AllowUsers" list (the grep command is just confirming the change we made,
because I'm not showing the actual "vi" session):

    sita-sv:~ # vim /etc/ssh/sshd_config

    sita-sv:~ # grep -i allowusers /etc/ssh/sshd_config
    AllowUsers sitaram git

    sita-sv:~ # service sshd restart
    Stopping sshd:                                                  [  OK  ]
    Starting sshd:                                                  [  OK  ]

----

### get pubkey access from client to server

This involves creating a keypair for yourself (using `ssh-keygen`), and
copying the public part of that keypair to the `~/.ssh/authorized_keys` file
on the server (using `ssh-copy-id`, if you're on Linux, or the manual method
described in the `ssh-copy-id` section in `doc/3-faq-tips-etc.mkd`).

    sita-lt:~ $ su - sita
    Password:

    sita@sita-lt:~ $ ssh-keygen
    Generating public/private rsa key pair.
    Enter file in which to save the key (/home/sita/.ssh/id_rsa):
    Created directory '/home/sita/.ssh'.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/sita/.ssh/id_rsa.
    Your public key has been saved in /home/sita/.ssh/id_rsa.pub.
    The key fingerprint is:
    8a:e0:60:1b:04:58:68:50:a4:d7:d0:3a:a5:2d:bf:0a sita@sita-lt.atc.tcs.com
    The key's randomart image is:
    +--[ RSA 2048]----+
    |===.             |
    |+o oo            |
    |o..=.            |
    |..= .            |
    |.o.+    S        |
    |.oo... .         |
    |E.. ...          |
    | .  .            |
    |  ..             |
    +-----------------+

    sita@sita-lt:~ $ ssh-copy-id -i ~/.ssh/id_rsa git@server
    git@server's password:
    /usr/bin/xauth:  creating new authority file /home/git/.Xauthority
    Now try logging into the machine, with "ssh 'git@server'", and check in:

      .ssh/authorized_keys

    to make sure we haven't added extra keys that you weren't expecting.

Double check to make sure you can log on to `git@server` without a password:

    sita@sita-lt:~ $ ssh git@server pwd
    /home/git

----

### get gitolite source

    sita@sita-lt:~ $ git clone git://github.com/sitaramc/gitolite gitolite-source
    Initialized empty Git repository in /home/sita/gitolite-source/.git/
    remote: Counting objects: 1157, done.
    remote: Compressing objects: 100% (584/584), done.
    remote: Total 1157 (delta 756), reused 912 (delta 562)
    Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
    Resolving deltas: 100% (756/756), done.

### install gitolite

Note that gitolite is installed from the *client*.  The `easy-install` script
runs on the client but installs gitolite on the server!

    sita@sita-lt:~ $ cd gitolite-source/src

<font color="red"> **This is the only gitolite specific command in a typical
install sequence**.  </font> Run it without any arguments to see a usage
message.  Run it without the `-q` to get a more verbose, pause-at-every-step,
install mode that allows you to change the defaults etc.


    sita@sita-lt:src $ ./gl-easy-install -q git server sitaram
    you are upgrading     (or installing first-time)     to v0.95-38-gb0ce84d
    setting up keypair...
    Generating public/private rsa key pair.
    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:
    Your identification has been saved in /home/sita/.ssh/sitaram.
    Your public key has been saved in /home/sita/.ssh/sitaram.pub.
    The key fingerprint is:
    2a:8e:88:42:36:7e:71:e8:cc:ff:4c:54:64:8e:cf:19 sita@sita-lt.atc.tcs.com
    The key's randomart image is:
    +--[ RSA 2048]----+
    |         o       |
    |        =        |
    |       . E       |
    |        + o      |
    |    .  .S+       |
    | + o ...         |
    |+ = + ..         |
    |oo B .o          |
    |+ o o..o         |
    +-----------------+
    creating gitolite para in ~/.ssh/config...
    finding/creating gitolite rc...
    installing/upgrading...
    Initialized empty Git repository in /home/git/repositories/gitolite-admin.git/
    Initialized empty Git repository in /home/git/repositories/testing.git/
    Pseudo-terminal will not be allocated because stdin is not a terminal.
    fatal: No HEAD commit to compare with (yet)
    [master (root-commit) 2f40d4b] start
     2 files changed, 13 insertions(+), 0 deletions(-)
     create mode 100644 conf/gitolite.conf
     create mode 100644 keydir/sitaram.pub
    cloning gitolite-admin repo...
    Initialized empty Git repository in /home/sita/gitolite-admin/.git/
    remote: Counting objects: 6, done.
    remote: Compressing objects: 100% (4/4), done.
    remote: Total 6 (delta 0), reused 0 (delta 0)
    Receiving objects: 100% (6/6), done.


    ---------------------------------------------------------------

    done!

    Reminder:
        *Your* URL for cloning any repo on this server will be
            gitolite:reponame.git
        *Other* users you set up will have to use
            git@server:reponame.git

        If this is your first time installing gitolite, please also:
            tail -31 ./gl-easy-install
        for next steps.

----

### examine what you have

    sita@sita-lt:src $ cd ~/gitolite-admin/

    sita@sita-lt:gitolite-admin $ git --no-pager log --stat
    commit 2f40d4bb80d424dc39aae5d0973f8c1b2e395666
    Author: git <git@sita-lt.atc.tcs.com>
    Date:   Thu Dec 24 21:39:15 2009 +0530

        start

     conf/gitolite.conf |   12 ++++++++++++
     keydir/sitaram.pub |    1 +
     2 files changed, 13 insertions(+), 0 deletions(-)

And that's really all.  Add keys to keydir here, edit conf/gitolite.conf as
needed, then add, commit, and push the changes to the server.  Try out that
`tail -31 ./gl-easy-install` too :)