10289c6d64
I had someone delete the admin repo on the server, then run gl-setup again, and complain that included config files did not get restored. There have been others (see below) before with similar demands, but those at least had the excuse of being provoked by genuine mistakes. This guy was intentionally breaking stuff server side. Wish I could say he was stupid, but actually he was probably smarter than I. Just that his idea of the limits of gitolite's responsibility was vastly different from mine. ---- [1] There was this guy who, as root, went on a "chmod go-rwx" spree for security, which bollixed up gitweb access to all his repos, so he tells me gitolite should be able to fix all the permissions on the next admin push at least? (That is, instead of just setting umask as it currently does, it should go on a chmod spree just like he did). [2] Then there was the guy who told me gitolite should re-create all the "gl-creater" files for his wildcard repos because he was restoring from a git push --mirror backup and that doesn't preserve those files? I tried to tell him that a git push --mirror doesn't preserve "config" or "description" or "info/exclude" or any of the other files that git (not gitolite) maintains, but he didn't care -- losing those did not affect him (or he never had them), but losing these affected access control, and it's my fault.
355 lines
14 KiB
Markdown
355 lines
14 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="#_conventions_used">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="#_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="#_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.
|
|
You can have any number of "hosting users" on one server; in fact every
|
|
user can host their own gitolite instance
|
|
* 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="_conventions_used"></a>
|
|
|
|
#### conventions used
|
|
|
|
Throughout the documentation, we use "sitaram" 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**.
|
|
|
|
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.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="_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="_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/sitaram.pub`.
|
|
|
|
* (U) on the server, as root, do the install (urpmi, yum, apt-get, etc.).
|
|
|
|
* on the server, "su - git", then as "git" user, run `gl-setup
|
|
/tmp/sitaram.pub`.
|
|
|
|
* on the client, run `cd; git clone git@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/sitaram.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 `gl-setup
|
|
/tmp/sitaram.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 use this method you'd better know enough about ssh to be able
|
|
to keep your keys straight, and you'd also better have password access to the
|
|
server so that if you screw up the keys you can still get on, or be able to
|
|
"su - git" from some other user on the server.
|
|
|
|
* from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
|
|
Put it in `/tmp/sitaram.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/sitaram.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
|
|
|
|
<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 (say one for each department, on some mega company-wide
|
|
server). 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
|
|
|
|
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://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd
|
|
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/uninstall.mkd
|
|
[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd#twokeys
|
|
[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd
|