419 lines
17 KiB
Markdown
419 lines
17 KiB
Markdown
# gitolite installatation
|
|
|
|
In this document:
|
|
|
|
* <a href="#_please_read_this_first">please read this first</a>
|
|
* <a href="#_important_notes">important notes</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="#_installation_and_setup">installation and setup</a>
|
|
* <a href="#_install_methods_and_deciding_which_one_to_use">install methods and deciding which one to use</a>
|
|
* <a href="#_conventions_used">conventions used</a>
|
|
* <a href="#_package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
|
|
* <a href="#_root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
|
|
* <a href="#_non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
|
|
* <a href="#_from_client_method_install_from_the_client_to_the_server">(from-client method) install from the client to the server</a>
|
|
* <a href="#_URLs_for_gitolite_managed_repos">URLs for gitolite-managed repos</a>
|
|
* <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
|
|
* <a href="#_package_method_and_root_method">package method and root method</a>
|
|
* <a href="#_from_client_method">from-client method</a>
|
|
* <a href="#_upgrading">upgrading</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 name="_please_read_this_first"></a>
|
|
|
|
### please read this first
|
|
|
|
<a name="_important_notes"></a>
|
|
|
|
#### important notes
|
|
|
|
Please make sure you understand the following points first.
|
|
|
|
* gitolite runs as a single user on a server, and is invoked via ssh. Thus,
|
|
every user on the server is a potential "gitolite host".
|
|
|
|
* 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][doc6] 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.
|
|
|
|
A gitolite setup has:
|
|
|
|
* a server
|
|
* a "hosting user" on the server -- the userid under which gitolite runs.
|
|
(Side note: there is *usually* only one hosting user per server (machine),
|
|
but gitolite makes it trivial to have as many as you want. Advanced users
|
|
can look [here][mgs]!)
|
|
* an "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
|
|
|
|
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="_requirements"></a>
|
|
|
|
#### requirements
|
|
|
|
<a name="_client_workstation"></a>
|
|
|
|
##### client/workstation
|
|
|
|
* git version 1.6.2 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.2 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
|
|
|
|
<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 indefero using the
|
|
'git clone' command:
|
|
|
|
git clone git://github.com/sitaramc/gitolite.git
|
|
# (OR)
|
|
git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
|
|
|
|
<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="_installation_and_setup"></a>
|
|
|
|
### installation and setup
|
|
|
|
<a name="methods"></a>
|
|
|
|
<a name="_install_methods_and_deciding_which_one_to_use"></a>
|
|
|
|
#### install methods and deciding which one to use
|
|
|
|
Gitolite has 4 install methods:
|
|
|
|
* **package method** if you have a gitolite RPM or a DEB available
|
|
* **root method** if you have root access to the server, and you plan to
|
|
have multiple "hosting users" on it
|
|
* **non-root method** if you don't have root access to the server, but you
|
|
do have at least one account with a password
|
|
* **from-client method** if you are not comfortable with public keys and
|
|
server side commands
|
|
|
|
Here's how you install using these 3 methods. Future upgrades are equally
|
|
easy -- the steps required for upgrading are marked "(U)".
|
|
|
|
<a name="_conventions_used"></a>
|
|
|
|
#### 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="_package_method_directly_on_the_server_using_RPM_DEB"></a>
|
|
|
|
#### (package method) directly on the server, using RPM/DEB
|
|
|
|
* from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
|
|
Put it in `/tmp/YourName.pub`.
|
|
|
|
* (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.).
|
|
|
|
* on the server, "su - gitolite", then as "gitolite" user, run `gl-setup
|
|
/tmp/YourName.pub`.
|
|
|
|
* on the client, run `cd; git clone gitolite@server:gitolite-admin`
|
|
|
|
<a name="_root_method_directly_on_the_server_manually_with_root_access"></a>
|
|
|
|
#### (root method) directly on the server, manually, with root access
|
|
|
|
* from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
|
|
Put it in `/tmp/YourName.pub`.
|
|
|
|
* (U) on the server, as root, do the following:
|
|
|
|
cd $HOME
|
|
git clone git://github.com/sitaramc/gitolite gitolite-source
|
|
cd gitolite-source
|
|
# now checkout whatever branch you want; for early adopters I suggest
|
|
# "pu", as in "git checkout -t origin/pu" for recent gits
|
|
mkdir -p /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
|
|
src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
|
|
|
|
* on the server, "su - git", then as "git" user, run `which gl-setup`. This
|
|
should respond with `/usr/local/bin/gl-setup`. If this is not what you
|
|
get, you have some `$PATH` issues. Make sure `/usr/local/bin` is in the
|
|
`$PATH` for the git user, and that no prior components of the path contain
|
|
another copy of `gl-setup`. You *must* run the one in the directory that
|
|
is the first argument of `gl-system-install` above.
|
|
|
|
* now run `gl-setup /tmp/YourName.pub`.
|
|
|
|
* on the client, run `cd; git clone git@server:gitolite-admin`
|
|
|
|
<a name="_non_root_method_directly_on_the_server_manually_without_root_access"></a>
|
|
|
|
#### (non-root method) directly on the server, manually, without root access
|
|
|
|
**WARNING: if you want to use this method your shell access to the git account
|
|
on the server should be via `su - git` from some other userid. If that is not
|
|
possible, you should (a) know the password in case you screw up the keys AND
|
|
(b) know how to force ssh to ask for a password if required, AND (c) know how
|
|
to handle multiple keys in ssh.**
|
|
|
|
* from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
|
|
Put it in `/tmp/YourName.pub`.
|
|
|
|
* if `$HOME/bin` is not on the default PATH, fiddle with your `.bashrc` or
|
|
`.bash_profile` or similar files and add it somehow.
|
|
|
|
* (U) on the server, as "git", do the following:
|
|
|
|
cd $HOME
|
|
git clone git://github.com/sitaramc/gitolite gitolite-source
|
|
# now checkout whatever branch you want; for early adopters I suggest
|
|
# "pu", as in "git checkout -t origin/pu" for recent gits
|
|
cd gitolite-source
|
|
mkdir -p $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
|
|
src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
|
|
|
|
* on the server, still as "git", run `gl-setup /tmp/YourName.pub`.
|
|
|
|
* on the client, run `cd; git clone git@server:gitolite-admin`
|
|
|
|
<a name="fc"></a>
|
|
|
|
<a name="_from_client_method_install_from_the_client_to_the_server"></a>
|
|
|
|
#### (from-client method) install from the client to the server
|
|
|
|
The advantage of this method is that it forces you to solve the ssh pubkey
|
|
problem **before** attempting to install. It works best if you have dedicated
|
|
userids, one on the server for installing gitolite, and one on the client for
|
|
administering it.
|
|
|
|
The disadvantage is that the admin user ends up with [two keys][twokeys] --
|
|
one for shell access (that he started with) and one for gitolite access (which
|
|
the script creates if needed).
|
|
|
|
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.
|
|
|
|
This method is verbosely documented in this [transcript][], including
|
|
*outputs* of the commands concerned.
|
|
|
|
<a name="_URLs_for_gitolite_managed_repos"></a>
|
|
|
|
### URLs for gitolite-managed repos
|
|
|
|
The URL for normal users (i.e., users other than the admin) is always of the
|
|
form "git@server:reponame". So, for instance, `git clone git@server:testing`
|
|
gets any valid user a copy of the "testing" repo.
|
|
|
|
In the first 3 install methods, the admin user will also use the same URL
|
|
format, like `git clone git@server:gitolite-admin`.
|
|
|
|
However, in the fourth ("from-client") method, the admin user needs a
|
|
different URL (`gitolite:reponame`) to gain access to the gitolite
|
|
repositories. Check [here][twokeys] for why.
|
|
|
|
<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][gash] 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.
|
|
|
|
<a name="_package_method_and_root_method"></a>
|
|
|
|
#### package method and root method
|
|
|
|
With the first two methods of installation, it's trivial to create multiple
|
|
gitolite instances. 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="_from_client_method"></a>
|
|
|
|
#### from-client method
|
|
|
|
You can do the same thing using this method also, but it's a little more
|
|
cumbersome. Instead, I'll describe a different scenario -- one "admin"
|
|
installing gitolite on different servers. You can adapt that to the above
|
|
case quite easily if you wish.
|
|
|
|
Thanks to Matt Perzel, the easy-install command now takes an optional 4th
|
|
parameter, which is the "nickname" of the gitolite server. It gets defined in
|
|
`~/.ssh/config`, and if not used it defaults to "gitolite".
|
|
|
|
So if you used the following command to install gitolite to 2 different
|
|
servers:
|
|
|
|
./src/gl-easy-install -q git my.1st.git.server admin_user1 gitolite_server_1
|
|
./src/gl-easy-install -q git my.2nd.git.server admin_user1 gitolite_server_2
|
|
|
|
you will find that `~/gitolite_server_1-admin` and `~/gitolite_server_2-admin`
|
|
have been created as respective clones. Or you can re-clone elsewhere:
|
|
|
|
cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git
|
|
cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git
|
|
|
|
<a name="_upgrading"></a>
|
|
|
|
### upgrading
|
|
|
|
Upgrading gitolite is easy. In each method above, just re-do the step that is
|
|
marked "(U)". Also, if you're using either of the two methods that use the
|
|
`src/gl-system-install` command, please make sure you give it the same
|
|
arguments!
|
|
|
|
If you've added any new hooks, please also run the next step (`gl-setup`)
|
|
also.
|
|
|
|
Also, remember that some new features may require additional settings in your
|
|
`~/.gitolite.rc` file.
|
|
|
|
<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`
|
|
|
|
<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]
|
|
|
|
----
|
|
|
|
[doc6]: 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
|
|
[gash]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
|