gitolite/doc/0-INSTALL.mkd

220 lines
8.3 KiB
Markdown
Raw Normal View History

2009-08-27 11:54:23 +02:00
# installing gitolite
[Update 2009-11-18: easy install now works from msysgit also!]
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
2009-10-25 14:53:15 +01:00
* typical example run
* advantages over the older install methods
* disadvantages
* manual install
* upgrades
* other notes
* next steps
2010-02-16 02:09:27 +01:00
* appendix A: server and client requirements
* appendix B: uninstalling gitolite
----
### easy install
There is an easy install script that makes installing very easy for the common
case. **This script will setup everything on the server, but you have to run
it on your workstation, NOT on the server!**
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`. If you do
not have `ssh-copy-id`, read doc/3-faq-tips-etc.mkd and look for
`ssh-copy-id` in that file for instructions
* you have a clone or an archive of gitolite somewhere on your workstation
* if you don't have one, just run `git clone git://github.com/sitaramc/gitolite`
Once you have all this, just `cd` to that clone and run `src/gl-easy-install`
and follow the prompts! (Running it without any arguments shows you usage
plus other useful info).
2009-10-25 14:53:15 +01:00
#### typical example run
A typical run for me is:
src/gl-easy-install -q git my.git.server sitaram
2009-10-25 14:53:15 +01:00
`-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/gl-easy-install` in a nice, syntax coloring, text
editor, and follow the instructions marked "MANUAL" :-)
2009-08-27 11:54:23 +02:00
### 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/gl-easy-install` 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.
2009-08-27 11:54:23 +02:00
### next steps
2009-08-27 11:54:23 +02:00
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.
<a name="server_reqs"></a>
2010-02-16 02:09:27 +01:00
### appendix A: server and client requirements
There are 3 machines *potentially* involved in installing and administering
gitolite.
#### server
This is where gitolite is eventually installed. You need a *normal* userid
(typically "git" but can be anything) on this machine; root access is *not*
needed, but it has to be some sort of Unix (not Windows).
You need the following software on it:
* git
* can be in a non-PATH location if you are unable to install it
normally; see the `$GIT_PATH` variable in the "rc" file
* perl
* default install is fine; no special modules are needed
* (a normal install of git also requires/installs perl, so you probably
have it already)
* openssh server
* (I guess any ssh server that can understand the `authorized_keys` file
format should work)
#### install workstation
Installing or upgrading the gitolite software itself is best done by running
the easy-install program from a gitolite clone.
This script is heavily dependent on bash, so you need a machine with a bash
shell. Even the bash that comes with msysgit is fine, if you don't have a
Linux box handy.
If you have neither Linux nor Windows+msysgit, you still have a few
alternatives:
* use a different userid on the same server (assuming it has bash)
* use the same userid on the same server (same assumption)
* manually simulate the script directly on the server (doable, but tedious)
#### admin workstation(s)
When you install gitolite, it creates a repository called "gitolite-admin" and
gives you permissions on it.
Administering gitolite (adding repos/users, assigning permissions, etc) is
done by cloning this repo, making changes to a file called
`conf/gitolite.conf`, adding users' pubkeys to `keydir/`, and pushing the
changes back to the server.
Which means all this can be done from *any* machine. You'll normally do it
from the same machine you used to install gitolite, but it doesn't have to be
the same one, as long as your pubkey has been added and permissions given to
allow you to push to the gitolite-admin repo.
2010-02-16 02:09:27 +01:00
<a name="uninstall"></a>
### uninstalling gitolite
Sometimes you might find gitolite is overkill -- you have only one user
(yourself) pushing maybe. Or maybe gitolite is just not enough -- you want a
web-based front end that users can use to manage their keys themselves, etc.,
in which case you'd probably switch to [github][g1], [girocco][g2],
[indefero][g3] or [gitorious][g4]. Either way, you'd like to uninstall
gitolite.
[g1]: http://github.com
[g2]: http://repo.or.cz/w/girocco.git
[g3]: http://www.indefero.net/
[g4]: http://gitorious.com/
Uninstalling gitolite is fairly easy. Just log on to the server and do the
following (assuming `$REPO_BASE` in the rc file was left at its default of
`~/repositories`; if not, adjust accordingly):
* edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
gitolite end` markers and all the lines between them. This will prevent
any of your users from attempting a push while you are doing this.
If you are the only user, and/or *need* one or more of those keys to
continue to access this account (like if one of them is your laptop or
your home desktop etc.) then instead of deleting the line you can just
delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
* Now remove (or move aside or rename to something else if you're paranoid)
the following files and directories.
~/.gitolite
~/.gitolite.rc
~/repositories/gitolite-admin.git
* Then remove all the `update` hooks that git installs on each repository.
The easiest way is:
find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
but you can do it manually if you want to be careful.
* Finally, any remote users that still have access must update their clone's
remote URLs (edit `.git/config` in the repo) to prefix `repositories/`
before the actual path used, in order for the remote to still work. This
is because you'll now be accessing it through plain ssh, which means you
have to give it the full path.