gitolite/doc/0-INSTALL.mkd
Sitaram Chamarty c4069dd85f (please read full commit message) upgrade behaviour changed
**upgrades no longer touch the config or the keydir**

When you first install gitolite, the easy install script has to do two
*distinct* things:

  * install the software
  * create and seed the gitolite-admin repo with a minimum config file
    and the newly created pubkey

That's fine for an install, because nothing exists yet anyway.

Subsequent invocations of the script should only do the first task (so
that gitolite itself can be upgraded), and not attempt to fiddle with
the config file and pubkeys.

Unfortunately, until now I had not been separating these two activities
cleanly enough.  For instance, the commit message for 8e47e01 said:

    IMPORTANT: we assume that $admin_name remains the same in an upgrade
    -- that's how we detect it is an upgrade!  Change that name or his
    pubkey, and you're toast!

Ouch!

So now I decided to clean things up.  The "Usage" message tells you
clearly what to do for an upgrade.

Should have been like this from the beginning, but hey we got there
eventually :)

----

Code-wise, this is a major refactor of the easy install script.  It uses
an old forgotten trick to get forward refs for bash functions ;-) and in
the process cleans up the flow quite a bit.
2009-11-06 15:37:03 +05:30

108 lines
3.9 KiB
Markdown

# installing gitolite
This document tells you how to install gitolite. After the install is done,
you may want to see the [admin document][admin] for adding users, repos, etc.
[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
There's an easy install script that requires bash (**strongly** recommended),
but if you have no bash or you're on one of the legacy Unixes there's a
slightly more manual process. Both are explained here.
In this document:
* easy install
* typical example run
* advantages over the older install methods
* disadvantages
* manual install
* upgrades
* other notes
* next steps
----
### easy install
There is an easy install script that makes installing very easy for the common
case. **This script is meant to be run on your workstation, not on the
server!** It will take care of all the server side work, *and* get you
"push-to-admin" too :-) In short, it does **everything**!
Assumptions/pre-requisites:
* you have a server to host gitolite
* git is installed on that server (and so is perl)
* you have a userid on that server
* you have ssh-pubkey (**password-less**) login to that userid
* (if you have only password access, run `ssh-keygen -t rsa` to create a
new keypair if needed, then run `ssh-copy-id user@host`)
* you have a clone or an archive of gitolite somewhere on your workstation
If so, just `cd` to that clone and run `src/00-easy-install.sh` and follow the
prompts! (Running it without any arguments shows you usage plus other useful
info).
#### typical example run
A typical run for me is:
src/00-easy-install.sh -q git my.git.server sitaram
`-q` stands for "quiet" mode -- very minimal output, no verbose descriptions
of what it is going to do, and no pauses unless absolutely needed. However,
if you're doing this for the first time or you appreciate knowing what it is
actually doing, I suggest you skip the `-q`.
#### advantages over the older install methods
* all ssh problems reduced to **just one pre-requisite**: enable ssh pubkey
(password-less) access to the server from your workstation first
* the script takes care of all the server side work
* when done:
* you get two different pubkeys (the original one for command line
access as before, plus a new one, created by the script, for gitolite
access)
* you can admin gitolite by commit+push a "gitolite-admin" repo, just
like gitosis (i.e., full "push to admin" power!)
#### disadvantages
* need a recent bash
### manual install
If you don't have bash, it's not very complicated to do it manually. Just
open the file `src/00-easy-install.sh` in a nice, syntax coloring, text
editor, and follow the instructions marked "MANUAL" :-)
### upgrades
Upgrading gitolite is easy.
To upgrade, pull the latest "master" (or other) branch in your gitolite repo
clone, then run the same exact command you ran to do the install, except you
can leave out the last argument.
And you might want to add a `-q` to speed things up :-)
Note that this only upgrades the software. Unlike earlier versions, it does
**not** touch the `conf/gitolite.conf` file or the contents of `keydir` in any
way. I decided that it is not possible to **safely** let an upgrade do
something meaningful with them -- fiddling with existing config files (as
opposed to merely creating one which did not exist) is best left to a human.
### other notes
* if you run `src/00-easy-install.sh` without the `-q` option, you will be
given a chance to edit `~/.gitolite.rc`. You can change any options (such
as paths, for instance), but be sure to keep the perl syntax -- you
*don't* have to know perl to do so, it's fairly easy to guess in this
limited case.
### next steps
The last message produced by the easy install script should tell you how to
add users, repos, etc., and you will find more details in the [admin][admin]
document.