1488973412
More and more people are using one of the first 3 methods of install (the ones that don't involve running "src/gl-easy-install" from the client side) usualy due to RPM/DEB being available now. Previously, the ending message on running that command was serving this purpose, and so it never really got written down in so many words. [thanks to antgel for catching this] ---- while we were there, we removed a now-obsolete section that talks about how to use just one key; there are better methods now
284 lines
11 KiB
Markdown
284 lines
11 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_side">client side</a>
|
|
* <a href="#server_side">server side</a>
|
|
* <a href="#installation_and_setup">installation and setup</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 is somewhat unusual as far as "server" software goes -- every
|
|
userid 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/6-ssh-troubleshooting.mkd][doc6] for help.
|
|
|
|
<a name="conventions_used"></a>
|
|
|
|
#### conventions used
|
|
|
|
We assume the admin user is "sitaram", and his workstation is called "client".
|
|
The hosting user is "git", and the server is called "server". Substitute your
|
|
values as needed.
|
|
|
|
<a name="requirements"></a>
|
|
|
|
#### requirements
|
|
|
|
<a name="client_side"></a>
|
|
|
|
##### client side
|
|
|
|
* 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_side"></a>
|
|
|
|
##### server side
|
|
|
|
* 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="installation_and_setup"></a>
|
|
|
|
### installation and setup
|
|
|
|
<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="from_client_method_install_from_the_client_to_the_server"></a>
|
|
|
|
#### (from-client method) install from the client to the server
|
|
|
|
This used to be the most common install method for a long time, and it is
|
|
still the one I use for most of my testing. The **main advantage** of this
|
|
method is that it **forces you** to solve the ssh pubkey problem **before**
|
|
attempting to install. Sadly, it also forces the admin to use a **different**
|
|
URL for 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 [doc/7-install-transcript.mkd][doc7],
|
|
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/9-uninstall.mkd][doc9unin]
|
|
|
|
----
|
|
|
|
[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd
|
|
[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd
|
|
[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd
|
|
[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd
|
|
[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd#why_two_keys_on_client
|