gitolite/doc/install.mkd
Sitaram Chamarty cf3dd885fc (some docfixes)
2012-04-21 22:29:56 +05:30

221 lines
7.4 KiB
Markdown

# installing gitolite
<font color="red">**NOTE**: if you're migrating from g2, there are some
settings that MUST be dealt with **before** running `gitolite setup`; please
start [here][migr]. RTFM is *mandatory* for migrations.</font>
----
[[TOC]]
----
## notes and naming conventions
Gitolite uses a single "real" (i.e., unix) user to provide secure access to
git repos to any number of "virtual" users, without giving them a shell.
The real user used is called the **hosting user**. Typically this user is
*git*, and that is what we will use throughout the documentation. However
RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
and examples accordingly.
Notes:
* Any unix user can be a hosting user.
* Which also means you can have several hosting users on the same machine.
* The URLs used will be of the form `git@host:reponame` (or its longer
equivalent starting with `ssh://`). The `.git` at the end is optional. I
recommend you leave it out, so your reponames are consistent with what the
conf file uses.
## #req requirements
### your 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.
### server
* Any Unix system with a posix compatible "sh".
* Git version 1.6.6 or later.
* Perl 5.8.8 or later.
* Openssh (almost any version). Optional if you're using [smart
http][http].
* A dedicated 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").
Also see the [WARNINGS][] page for more on what gitolite expects on the server
side.
### client
* Openssh client.
* Git 1.6.6 or later. Almost any git client will work, as long as it knows
how to use ssh keys and send the right one along.
## getting the software
git clone git://github.com/sitaramc/gitolite
## the actual install
Gitolite has only one server side "command" now, much like git itself. This
command is `gitolite`. You don't need to place it anywhere special; worst
case you run it with the full path.
"Installation" consists of the following options:
1. Keep the sources anywhere and use the full path to run the `gitolite`
command.
2. Keep the sources anywhere and symlink *just* the `gitolite` program to
some directory on your `$PATH`.
3. Copy the sources somewhere and use that path to run the `gitolite`
command.
Option 2 is the best for general use.
There is a program called 'install' that helps you do these easily. Assuming
your cloned the repo like this:
git clone git://github.com/sitaramc/gitolite
you can run the 'install' command in 3 different ways:
# option 1
gitolite/install
# option 2
gitolite/install -ln
# defaults to $HOME/bin, or use a specific directory:
gitolite/install -ln /usr/local/bin
# option 3
gitolite/install -to /usr/local/gitolite/bin
Creating a symlink doesn't need a separate program but 'install' also runs
`git describe` to create a VERSION file, which, trust me, is important!
**Next step**: run [**setup**][setup].
## upgrading
* Update your clone of the gitolite source.
* Repeat the install command you used earlier (make sure you use the same
arguments as before).
* Run `gitolite setup`.
## packaging gitolite
Here are the requirements for gitolite:
* The programs `gitolite` and `gitolite-shell`, and the directories
`commands`, `lib`, `syntactic-sugar`, `triggers`, and `VREF` must all be
in the same directory.
It doesn't matter what this directory is. As an example, Fedora keeps
git's 150 executables in /usr/libexec/git-core, so /usr/libexec/gitolite
may be a good choice; it's upto you.
The rest of this section will assume you chose /usr/libexec/gitolite as
the location. Adjust as needed.
* The program `/usr/libexec/gitolite/gitolite` must then be *symlinked* to
some directory in the PATH. Do not *copy* it; it must be a symlink.
* The `Gitolite` subdirectory in `/usr/libexec/gitolite/lib` can stay there,
**OR**, if your distro policies don't allow that, can be put in any
directory in perl's `@INC` path (such as `/usr/share/perl5/vendor_perl`).
* Finally, a file called `/usr/libexec/gitolite/VERSION` must contain a
suitable version string.
## #migr migrating
<font color="gray">This section is about migrating from older gitolite to
"g3". If you're migrating from gitosis, see [here][gsmigr].</font>
First things first: g2 will be supported for a good long time for critical
bugs, although enhancements and new features won't happen.
If you're an existing (gitolite v1.x or v2.x) user, and wish to migrate , here
are the steps:
### pre-migration checks
1. Check the [dev-status][] page to make sure all the features you want have
been implemented in g3.
2. Read the [g2 migration][g2migr] page to see what changes affect you and
your users, and how much time it might take you to migrate. (The closer
you were to a default install of the old gitolite, the less time a
migration will take.)
### the actual migration
**Note**: nothing in any of the gitolite install/setup/etc will ever touch the
*data* in any repository except the gitolite-admin repo. The only thing it
will normally touch in normal repos is the `update` hook.
1. **On the server**, carefully wipe out the old gitolite:
* The **code**
* Delete or move away all the old gitolite scripts. Check the path
to the gl-auth-command in `~/.ssh/authorized_keys` if you forgot
where you put them.
* Delete or move away the two directories named in the two variables
`GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`.
* The **rc file**
* Rename `~/.gitolite.rc` to something else.
* The **admin repo**
* clone `~/repositories/gitolite-admin.git` to someplace safe
* then delete `~/repositories/gitolite-admin.git`
(Make sure you do not delete any other repos!)
* The **admin directory**.
* If you need to preserve logs, move the ~/.gitolite/logs` directory
somewhere else.
* If you added any custom hooks and wish to preserve them, move the
~/.gitolite/hooks` directory somewhere else.
* Delete `~/.gitolite`.
2. Read about [presetting][rc-preset] the rc file; if you're using any
variables listed as requiring preset, follow those instructions to create
your new rc file.
3. Install gitolite g3; see [quick install and setup][qi] or [install][]
followed by [setup][].
4. Make sure your gitolite-admin clone has the correct pubkey for the
administrator in its `keydir` directory, then run [`gitolite push
-f`][bypass] to overwrite the "default" admin repo created by the install.
5. Handle any errors, look for migration issues, etc., as described in the
links at the top of this page.
This also includes building up your new `~/.gitolite.rc` file.
You're done.