e3bc6e7c48
major changes - (src) one error message got more detail - long overdue fixup to developer notes doc plus many minor changes that have been piling up PS: to dig into the "alliterative animal" comment, check the channel logs around aug 23rd ;-)
499 lines
19 KiB
Markdown
499 lines
19 KiB
Markdown
# 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").
|
|
|
|
In this document:
|
|
|
|
* <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
|
|
* <a href="#_side_note_upgrading">(side note) upgrading</a>
|
|
* <a href="#_package_method">package method</a>
|
|
* <a href="#_non_root_method">non-root method</a>
|
|
* <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a>
|
|
* <a href="#_root_method">root method</a>
|
|
* <a href="#_troubleshooting">troubleshooting</a>
|
|
* <a href="#_important_points_to_note">important points to note</a>
|
|
* <a href="#_naming_conventions_used">naming conventions used</a>
|
|
* <a href="#_requirements">requirements</a>
|
|
* <a href="#_client_workstation">client/workstation</a>
|
|
* <a href="#_server">server</a>
|
|
* <a href="#_technical_skills">technical skills</a>
|
|
* <a href="#_getting_the_gitolite_software">getting the gitolite software</a>
|
|
* <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
|
|
* <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
|
|
* <a href="#_uninstalling">uninstalling</a>
|
|
* <a href="#_cleaning_out_a_botched_install">cleaning out a botched install</a>
|
|
* <a href="#_uninstalling_gitolite_completely">uninstalling gitolite completely</a>
|
|
* <a href="#_appendix_a_the_from_client_method">appendix a: the from-client method</a>
|
|
* <a href="#_appendix_b_PATH_issues_for_gl_setup">appendix b: PATH issues for gl-setup</a>
|
|
|
|
----
|
|
|
|
<a name="_installing_and_upgrading_gitolite"></a>
|
|
|
|
### 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*).
|
|
|
|
<a name="_side_note_upgrading"></a>
|
|
|
|
#### (side note) 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.
|
|
|
|
[admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
|
|
[http]: http://sitaramc.github.com/gitolite/doc/http-backend.html
|
|
|
|
<a name="_package_method"></a>
|
|
|
|
#### 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
|
|
|
|
<a name="_non_root_method"></a>
|
|
|
|
#### 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).
|
|
|
|
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
|
|
cd gitolite
|
|
src/gl-system-install
|
|
# defaults to being the same as:
|
|
# 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
|
|
|
|
<a name="_upgrading_from_from_client_method_to_non_root_method"></a>
|
|
|
|
##### 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.
|
|
|
|
<a name="_root_method"></a>
|
|
|
|
#### 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
|
|
cd gitolite
|
|
src/gl-system-install
|
|
# defaults to being the same as:
|
|
# 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
|
|
|
|
----
|
|
|
|
<a name="_troubleshooting"></a>
|
|
|
|
### troubleshooting
|
|
|
|
* The most common thing that goes wrong in an install is something to do
|
|
with 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][glgas] and the [ssh
|
|
troubleshooting][glsts] 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 b 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.
|
|
|
|
<a name="_important_points_to_note"></a>
|
|
|
|
### important points to note
|
|
|
|
* 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. Advanced users can
|
|
look [here][mgs]!)
|
|
|
|
* 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 [doc/ssh-troubleshooting.mkd][glsts] 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.
|
|
|
|
<a name="_naming_conventions_used"></a>
|
|
|
|
### 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.
|
|
|
|
<a name="_requirements"></a>
|
|
|
|
### requirements
|
|
|
|
<a name="_client_workstation"></a>
|
|
|
|
#### 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
|
|
* if you're using the "from-client" method of install (see below), the bash
|
|
shell is needed
|
|
* again, msysgit on Windows is fine
|
|
|
|
<a name="_server"></a>
|
|
|
|
#### 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").
|
|
|
|
<a name="_technical_skills"></a>
|
|
|
|
#### 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.
|
|
|
|
<a name="_getting_the_gitolite_software"></a>
|
|
|
|
### 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/
|
|
|
|
<a name="_getting_a_tar_file_from_a_clone"></a>
|
|
|
|
#### 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.
|
|
|
|
--------------------------------------------------------
|
|
|
|
<a name="_special_cases_multiple_gitolite_servers"></a>
|
|
|
|
### special cases -- multiple gitolite servers
|
|
|
|
(**Advanced users only, please!**)
|
|
|
|
There is no gitolite "daemon"; it gets invoked via sshd which calls
|
|
"gl-auth-command" via the "command=" option in the authkeys file (see
|
|
[gitolite and ssh][glgas] for more).
|
|
|
|
If you think about it, this means every real (unix) user on the system can
|
|
host her own gitolite server!
|
|
|
|
Of course, one doesn't normally do that in the interests of sanity, but let's
|
|
say you want to create one gitolite instance for each department on some
|
|
company-wide mega-server.
|
|
|
|
Using one of the first two methods of installation, it's trivial to create
|
|
multiple gitolite instances -- essentially any Unix user can then run
|
|
`gl-setup` with some pubkey filename as an argument and that user is now a
|
|
gitolite host.
|
|
|
|
You can even do this without giving shell access to the admins. Here's an
|
|
example with just two "departments", and their admins Alice and Bob:
|
|
|
|
* create userids `webbrowser_repos` and `webserver_repos`
|
|
* ask Alice and Bob for their pubkeys; copy them to the respective home
|
|
directories for convenience
|
|
* run `su - webbrowser_repos`, then `gl-setup alice.pub`
|
|
* (similarly with `webserver_repos` and `bob.pub`, and so on for others)
|
|
|
|
That's it. The URL for all web browser projects is now something like
|
|
`webbrowser_repos@server:reponame`, and similarly for the others.
|
|
|
|
Notice that you only have to do this once for each "department", and it's
|
|
really just one command after creating the userid. None of these admins need
|
|
to have a command line on the server, so don't give them the passwords if you
|
|
don't need to -- the pubkey will allow them to be gitolite admins on their
|
|
domain, and that's quite enough for normal operations.
|
|
|
|
<a name="_uninstalling"></a>
|
|
|
|
### uninstalling
|
|
|
|
<a name="_cleaning_out_a_botched_install"></a>
|
|
|
|
#### 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`
|
|
|
|
<a name="_uninstalling_gitolite_completely"></a>
|
|
|
|
#### uninstalling gitolite completely
|
|
|
|
There's some duplication between this and the previous section, but
|
|
uninstalling gitolite is described in great detail in
|
|
[doc/uninstall.mkd][doc9unin]
|
|
|
|
----
|
|
|
|
<a name="_appendix_a_the_from_client_method"></a>
|
|
|
|
### appendix a: the from-client method
|
|
|
|
This method was the only install mode at one time, but the newer ones are much
|
|
better, so it's kinda legacy now (Wow -- fancy something being "legacy" in
|
|
software that is not yet 2 years old!)
|
|
|
|
The only advantage of this method is that it forces you to solve the ssh
|
|
pubkey problem **before** attempting to install.
|
|
|
|
But I'm not sure if that is worth the hassle of supporting an install scheme
|
|
that ends up with the admin user having [two keys][twokeys], though. And this
|
|
in turn forces the admin to use a different URL to access gitolite repos than
|
|
normal users, which seems to confuse a heck of a lot of people who don't read
|
|
the prominently displayed messages and/or the documentation.
|
|
|
|
All in all, I plan to obsolete it eventually. Meanwhile, it is verbosely
|
|
documented in this [transcript][], including *outputs* of the commands
|
|
concerned.
|
|
|
|
<a name="_appendix_b_PATH_issues_for_gl_setup"></a>
|
|
|
|
### appendix b: 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 `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 `src/gl-system-install` command (or
|
|
`/usr/local/bin` by default)
|
|
* non-root method: the first argument to the `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.
|
|
|
|
[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
|
|
[doc9unin]: http://sitaramc.github.com/gitolite/doc/uninstall.html
|
|
[twokeys]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#twokeys
|
|
[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
|
|
[mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers
|
|
[glgas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
|
|
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
|