6e29365316
I got tired of being told "TL;DR". Now the online versions of most documents fit on a page or two, or at least most of them do. The rest has been split out (and you can see the links to the split out sections right where the text is in the raw Markdown). This is much more pleasant to read, and I've improved the linking so it's much less effort for me to keep the links correct.
408 lines
16 KiB
Markdown
408 lines
16 KiB
Markdown
# F=install gitolite installation
|
|
|
|
(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 [this][http] to install gitolite to support "smart http").
|
|
|
|
## installing and upgrading gitolite
|
|
|
|
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.
|
|
|
|
A bare minimum gitolite setup has:
|
|
|
|
* a server
|
|
* a "hosting user" on the server (a real Unix userid; we use "git" in this
|
|
document, although RPM/DEB installs use "gitolite")
|
|
* a virtual "admin user" -- the user who sets up gitolite and configures it
|
|
* the admin user's client or workstation, from which he does all his work
|
|
|
|
Gitolite allows 3 methods of install. The two most common are (1) the
|
|
**package method**, used if you have a gitolite RPM or a DEB available, and
|
|
(2) the **non-root method** which is the preferred manual install mode. Less
|
|
commonly used is (3) the **root method**, which is useful if you plan to have
|
|
multiple "hosting users" on the same server.
|
|
|
|
These install methods are described in detail below. (*Once you finish the
|
|
install, read the [admin document][admin] to administer your gitolite
|
|
installation*).
|
|
|
|
### F=rpmdeb package method
|
|
|
|
(Unlike in the rest of this document, we use "gitolite" as the "hosting user"
|
|
instead of "git" here, because that is the user that both the Fedora and
|
|
Debian packages create. Your distro/OS may vary.)
|
|
|
|
On your *workstation*:
|
|
|
|
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
|
|
|
|
On your *server*, as *root*:
|
|
|
|
yum install gitolite # or 'apt-get install gitolite', or whatever
|
|
# this is the only step you need to repeat when upgrading gitolite
|
|
|
|
# current RPM/DEB create a hosting user called "gitolite"
|
|
su - gitolite
|
|
|
|
# (now as gitolite)
|
|
gl-setup /tmp/YourName.pub
|
|
|
|
On your *workstation*:
|
|
|
|
git clone gitolite@server:gitolite-admin
|
|
|
|
### F=nonroot non-root method
|
|
|
|
**IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method
|
|
you had better know the password to the hosting user on the server, or be able
|
|
to `su` to it from root, just in case you manage to lock yourself out by
|
|
messing with the keys.
|
|
|
|
**NOTE**: This method is exhaustively described in the [tutorial][tut], if
|
|
you're interested. (That tutorial is by someone else but it's nice enough for
|
|
me to link it here).
|
|
|
|
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
|
|
|
|
On your *workstation*:
|
|
|
|
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
|
|
|
|
On your *server*, as *git* (the "hosting user"), first check if `$HOME/bin` is
|
|
on the default PATH. If not, fiddle with the `.bashrc` or `.bash_profile` or
|
|
similar files and add it somehow. Then:
|
|
|
|
git clone git://github.com/sitaramc/gitolite
|
|
gitolite/src/gl-system-install
|
|
# defaults to being the same as:
|
|
# gitolite/src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
|
|
|
|
# to upgrade gitolite, repeat the above commands. Make sure you use the
|
|
# same arguments for the last command each time.
|
|
|
|
gl-setup /tmp/YourName.pub
|
|
|
|
On your *workstation*:
|
|
|
|
git clone git@server:gitolite-admin
|
|
|
|
#### F=upgrfromclient upgrading from from-client method to non-root method
|
|
|
|
Since the from-client method is now deprecated for reasons explained
|
|
elsewhere, some folks may want to do their next upgrade using the non-root
|
|
method.
|
|
|
|
There are many, many ways to skin this cat; here's one way:
|
|
|
|
* follow non-root install but stop after the gl-system-install step
|
|
|
|
* temporarily rename your `~/.gitolite.rc` file to something else
|
|
|
|
* now run the gl-setup step
|
|
|
|
(background: this will create a default rc file with default values, but
|
|
crucially, it will give you the correct values for two very critical
|
|
variables that are not used in the old from-client install method)
|
|
|
|
* edit `~/.gitolite.rc` and bring in any non-default settings you may have
|
|
had in your old rc file.
|
|
|
|
When you're done, the only difference between your old and current rc
|
|
files should be that the `$GL_PACKAGE_CONF` and the `$GL_PACKAGE_HOOKS`
|
|
variables are no longer commented out and look somewhat like this:
|
|
|
|
$GL_PACKAGE_CONF = '/home/git/share/gitolite/conf';
|
|
$GL_PACKAGE_HOOKS = '/home/git/share/gitolite/hooks';
|
|
|
|
Now save the file.
|
|
|
|
### F=root root method
|
|
|
|
On your *workstation*:
|
|
|
|
* copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
|
|
|
|
On your *server*, as *root*:
|
|
|
|
git clone git://github.com/sitaramc/gitolite
|
|
gitolite/src/gl-system-install
|
|
# defaults to being the same as:
|
|
# gitolite/src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
|
|
|
|
# to upgrade gitolite, repeat the above commands. Make sure you use the
|
|
# same arguments for the last command each time.
|
|
|
|
# now create your "hosting user" ('git' in our examples) using whatever
|
|
# command your distro expects you to use
|
|
|
|
# switch to the hosting user
|
|
su - git
|
|
|
|
# (now as git)
|
|
gl-setup /tmp/YourName.pub
|
|
|
|
On your *workstation*:
|
|
|
|
git clone git@server:gitolite-admin
|
|
|
|
### #upgrade upgrading
|
|
|
|
Upgrading is easy; you just re-run some of the same commands used for install.
|
|
These commands are clearly noted in the install instructions below.
|
|
|
|
However, if you've added any new hooks, you must also run the next step (the
|
|
`gl-setup` command), although this time you don't need to supply a pubkey
|
|
filename as an argument.
|
|
|
|
## #insttrouble if you run into trouble...
|
|
|
|
If you run into trouble, please read the following sections. They have
|
|
background information that may help you, or additional steps you can take to
|
|
troubleshoot or fix the problem.
|
|
|
|
### common install problems
|
|
|
|
The most common problem is usually ssh. Here are three facts of ssh:
|
|
|
|
* ssh is a pain
|
|
* most people don't know ssh well enough
|
|
* even people who think they do, don't
|
|
|
|
Please read how [gitolite uses ssh][gl_ssh] and the [ssh
|
|
troubleshooting][sts] documents before asking for help.
|
|
|
|
If you've tried multiple methods of install, you may have multiple copies of
|
|
the sources lying around. This could be a problem; see [appendix a][instpath]
|
|
for how to detect and deal with this.
|
|
|
|
If none of this works read the rest of this document, understand it as much as
|
|
you can, then ask for help.
|
|
|
|
### #instnameconv naming conventions used
|
|
|
|
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". **Please substitute your values as needed**.
|
|
|
|
**If you're using DEB or RPM**, the installer creates a user called
|
|
"gitolite", so substitute that for "git" anywhere in the docs where the
|
|
"hosting user" is mentioned as "git".
|
|
|
|
Also, we often say "the rc file". This means `~/.gitolite.rc` on the server.
|
|
And when we say the "access control rules", or "conf file", or "config file",
|
|
we mean `conf/gitolite.conf` on your gitolite-admin clone.
|
|
|
|
### F=instbg helpful background information
|
|
|
|
* gitolite runs as a single (real) user on a server, and is invoked via ssh.
|
|
Traditionally, this "hosting user" is "git", and thus all git URLs start
|
|
with `ssh://git@server` (or the equivalent shorter form `git@server:`).
|
|
|
|
* RPM/DEB create and use "gitolite" as the hosting user
|
|
|
|
* there is *usually* only one hosting user per server (machine), but
|
|
gitolite makes it trivial to have as many as you want. In fact, every
|
|
user on the server is a potential hosting user.
|
|
|
|
* using this single user and sshd (or httpd) authentication, gitolite allows
|
|
you to create any number of "virtual" users. Virtual user names only mean
|
|
something to gitolite, and they need not be the same as any real userid on
|
|
the server or any of the clients accessing it.
|
|
|
|
* the first such virtual user is the "admin user", created during the
|
|
install sequence.
|
|
|
|
* gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not
|
|
assume you know all about ssh -- most people **don't**. If in doubt, use
|
|
a dedicated userid on both client and server for installation and
|
|
administration of gitolite.
|
|
|
|
To make matters worse, ssh problems in gitolite don't always look like ssh
|
|
problems. See the [ssh troubleshooting][sts] document for help.
|
|
|
|
* gitolite **does NOT** like it when people with shell access to the server
|
|
fiddle with files and directories it controls.
|
|
|
|
Apparently this was not obvious to some people.
|
|
|
|
It is possible to have the server and the client be the same machine, and even
|
|
the admin user be also the hosting user, (i.e., `sitaram@server` can install
|
|
and administer a gitolite setup running under `sitaram@server`, a situation
|
|
that is common with some hosting services). It's actually fairly easy and
|
|
**safe** to do, **as long as you have password access to the server** for
|
|
emergency use. However, I will not be documenting it because (a) if you know
|
|
ssh you'll know how to extrapolate my instructions to do this and (b) if you
|
|
don't know ssh it'll be a nightmare to support you.
|
|
|
|
### F=instrequire requirements
|
|
|
|
#### client/workstation
|
|
|
|
* git version 1.6.6 or greater
|
|
* even msysgit on Windows is fine; please don't ask me for help if
|
|
you're using putty, plink, puttygen, etc., for ssh; I recommend
|
|
msysgit for Windows and the openssh that comes with it
|
|
|
|
#### server
|
|
|
|
* any Unix system with a posix compatible "sh".
|
|
* people using "csh" or derivatives please don't ask me for help -- tell
|
|
your admin csh is not posix compatible
|
|
* git version 1.6.6 or greater
|
|
* 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 (but since git requires it anyway, you probably have it)
|
|
* openssh or any ssh that can understand the `authorized_keys` file format
|
|
(probably optional if you're using the http backend)
|
|
* a Unix userid to be the hosting user, usually "git" but it can be any
|
|
user, even your own normal one. (If you're using an RPM/DEB the install
|
|
probably created one called "gitolite").
|
|
|
|
#### technical skills
|
|
|
|
* if you're installing gitolite, you're a "system admin", like it or not.
|
|
Ssh is therefore a necessary skill. Please take the time to learn at
|
|
least enough to get passwordless access working.
|
|
|
|
* you also need to be somewhat familiar with git itself. You cannot
|
|
administer a whole bunch of git repositories if you don't know the basics
|
|
of git.
|
|
|
|
* some familiarity with Unix and shells is probably required
|
|
|
|
* regular expressions are a big part of gitolite in many places but
|
|
familiarity is not necessary to do basic access control.
|
|
|
|
### F=_getgl getting the gitolite software
|
|
|
|
You can get the latest version of gitolite from github or google code using
|
|
the 'git clone' command:
|
|
|
|
git clone git://github.com/sitaramc/gitolite.git
|
|
# (OR)
|
|
git clone https://code.google.com/p/gitolite/
|
|
|
|
#### getting a tar file from a clone
|
|
|
|
If you are on an internal network and cannot clone the gitolite repo, you can
|
|
do the clone on some other machine and create a tar file from it to use on the
|
|
internal network. Here's how:
|
|
|
|
git clone git://github.com/sitaramc/gitolite.git
|
|
# (OR)
|
|
git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
|
|
cd gitolite
|
|
make master.tar
|
|
# or maybe "make pu.tar"
|
|
|
|
Please use the make command as shown, not a plain "git archive", because the
|
|
Makefile adds a file called `.GITOLITE-VERSION` that will help you identify
|
|
which version you are using.
|
|
|
|
## #_instappendices appendixes
|
|
|
|
The following sections have some miscellaneous information that does not
|
|
cleanly to fit anywhere else.
|
|
|
|
### #instpath appendix a: PATH issues for gl-setup
|
|
|
|
If you've tried multiple methods of install, you may have multiple copies of
|
|
the sources lying around, and when you ran `gl-setup` it picked up the wrong
|
|
one. This might also happen if the directory you supplied as the first
|
|
argument to `gitolite/src/gl-system-install` is not even in the `$PATH`.
|
|
|
|
Run `su - git` then `which gl-setup` to see which it picked up. This is what
|
|
it should be for each method:
|
|
|
|
* RPM/DEB method: probably `/usr/bin`
|
|
* root method: the first argument to the `gitolite/src/gl-system-install` command (or
|
|
`/usr/local/bin` by default)
|
|
* non-root method: the first argument to the `gitolite/src/gl-system-install` command
|
|
(or `$HOME/bin` by default)
|
|
|
|
If this is not what you get, remove the partially installed or extraneous
|
|
sources, if any, and try again. Or fix your `$PATH`.
|
|
|
|
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 `/usr/bin` and `/usr/local/bin` are
|
|
usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
|
|
Good luck.
|
|
|
|
### #clean appendix b: cleaning out a botched install
|
|
|
|
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
|
|
here's how to clean the slate.
|
|
|
|
* client-side
|
|
* edit `~/.ssh/config` and delete the paragraph starting with `host
|
|
gitolite`, if present.
|
|
* remove `~/gitolite-admin`
|
|
* server-side
|
|
* edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite
|
|
start` and `# gitolite end` inclusive.
|
|
* remove `~/.gitolite`, `~/.gitolite.rc` and
|
|
`~/repositories/gitolite-admin.git`
|
|
* depending on which install method you used, you may also need to clean
|
|
out all gitolite files from `/usr/local/bin` or `$HOME/bin`, and then
|
|
delete `/var/gitolite/conf` and `/var/gitolite/hooks` or
|
|
`$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks`
|
|
|
|
### F=_uninstall appendix c: uninstalling gitolite completely
|
|
|
|
(There's some duplication between this and the previous section).
|
|
|
|
Uninstalling gitolite is fairly easy, although it is manual. (We'll assume
|
|
`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
|
|
not, adjust accordingly):
|
|
|
|
**server side tasks**
|
|
|
|
* 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
|
|
|
|
* You can remove all of `~/repositories` if you have not really started
|
|
using gitolite properly yet; that's your choice.
|
|
|
|
If you *do* need to preserve the other repos and continue to use them,
|
|
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.
|
|
|
|
**client side tasks**
|
|
|
|
* 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.
|
|
|
|
* Finally, you as the gitolite admin *nay* have a host stanza for "gitolite"
|
|
in your *client*'s `~/.ssh/config`. Find and delete lines that look like
|
|
this:
|
|
|
|
host gitolite
|
|
user git
|
|
hostname your.server
|
|
port 22
|
|
identityfile ~/.ssh/your-gitolite-admin-username
|