quick install in main README
requested by someone who told me it's high time I catered to the experts too, and saved them some time on the install! I took the opportunity to streamline the README (especially the "what" section), and to prioritise the non-root method over the root method in the install doc.
This commit is contained in:
Sitaram Chamarty
parent
6a3cd5d6b1
commit
ddf4330d1e
93
README.mkd
93
README.mkd
|
|
@ -5,15 +5,63 @@
|
||||||
Gitolite allows you to setup git hosting on a central server, with
|
Gitolite allows you to setup git hosting on a central server, with
|
||||||
fine-grained access control and many (many!) more powerful features.
|
fine-grained access control and many (many!) more powerful features.
|
||||||
|
|
||||||
**Impatient?** The [install][install] document has a quick install section at
|
----
|
||||||
the top. Just remember that "impatient" does not always mean "successful" ;-)
|
|
||||||
|
In this document:
|
||||||
|
|
||||||
|
* <a href="#_quick_install">quick install</a>
|
||||||
|
* <a href="#_what">what</a>
|
||||||
|
* <a href="#_why">why</a>
|
||||||
|
* <a href="#_main_features">main features</a>
|
||||||
|
* <a href="#_security">security</a>
|
||||||
|
* <a href="#_contact_and_license">contact and license</a>
|
||||||
|
|
||||||
----
|
----
|
||||||
|
|
||||||
Gitolite is an access control layer on top of git, which allows access control
|
<a name="_quick_install"></a>
|
||||||
down to the branch level, including specifying who can and cannot *rewind* a
|
|
||||||
given branch. [Here][who]'s some information on some of the projects and
|
### quick install
|
||||||
people using gitolite (and who, in turn, have helped shape its features).
|
|
||||||
|
If you're comfortable with Unix and ssh, the following steps should work.
|
||||||
|
<font color="gray">(However, gitolite has lots and lots of useful features;
|
||||||
|
don't miss out on them by skipping the excellent
|
||||||
|
[documentation][docs]!)</font>
|
||||||
|
|
||||||
|
* create a user called `git`. Login to this user.
|
||||||
|
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
|
||||||
|
* now run these commands:
|
||||||
|
|
||||||
|
git clone git://github.com/sitaramc/gitolite
|
||||||
|
cd gitolite
|
||||||
|
src/gl-system-install
|
||||||
|
gl-setup ~/YourName.pub
|
||||||
|
|
||||||
|
You're done. Now run `git clone git@server:gitolite-admin` on your
|
||||||
|
workstation and [add users and repos][aur].
|
||||||
|
|
||||||
|
[aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
|
||||||
|
|
||||||
|
<a name="_what"></a>
|
||||||
|
|
||||||
|
### what
|
||||||
|
|
||||||
|
Gitolite is an access control layer on top of git. Here's an "executive
|
||||||
|
summary":
|
||||||
|
|
||||||
|
* use a single unix user ("real" user) on the server
|
||||||
|
* provide access to many gitolite users
|
||||||
|
* they are not "real" users
|
||||||
|
* they do not get shell access
|
||||||
|
* control access to many git repositories
|
||||||
|
* read access controlled at the repo level
|
||||||
|
* write access controlled at the branch/tag/file/directory level,
|
||||||
|
including who can rewind, create, and delete branches/tags
|
||||||
|
* can be installed without root access, assuming git and perl are already
|
||||||
|
installed
|
||||||
|
* authentication is most commonly done using sshd, but you can also use
|
||||||
|
httpd if you prefer (this may require root access).
|
||||||
|
* several other neat features described below and elsewhere in the
|
||||||
|
[doc/][docs] directory.
|
||||||
|
|
||||||
Gitolite comes with a **huge** amount of documentation. If you're absolutely
|
Gitolite comes with a **huge** amount of documentation. If you're absolutely
|
||||||
new, the suggested reading order is this:
|
new, the suggested reading order is this:
|
||||||
|
|
@ -27,36 +75,11 @@ new, the suggested reading order is this:
|
||||||
* (if you're migrating from gitosis, read [this][migr])
|
* (if you're migrating from gitosis, read [this][migr])
|
||||||
|
|
||||||
There is also a **[master TOC of all gitolite documentation][docs]**; use your
|
There is also a **[master TOC of all gitolite documentation][docs]**; use your
|
||||||
browser's search function (Ctrl-F, usually) to look for likely sounding words
|
browser's search function to look for likely sounding words or just browse
|
||||||
or just browse around -- you never know what you'll find!
|
around -- you never know what you'll find!
|
||||||
|
|
||||||
----
|
[Here][who]'s some information on some of the projects and
|
||||||
|
people using gitolite (and who, in turn, have helped shape its features).
|
||||||
In this document:
|
|
||||||
|
|
||||||
* <a href="#_what">what</a>
|
|
||||||
* <a href="#_why">why</a>
|
|
||||||
* <a href="#_main_features">main features</a>
|
|
||||||
* <a href="#_security">security</a>
|
|
||||||
* <a href="#_contact_and_license">contact and license</a>
|
|
||||||
|
|
||||||
----
|
|
||||||
|
|
||||||
<a name="_what"></a>
|
|
||||||
|
|
||||||
### what
|
|
||||||
|
|
||||||
Gitolite lets you use a single user on a server to host many git repositories
|
|
||||||
and provide access to many developers, without having to give them real
|
|
||||||
userids on or shell access to the server. Authentication is most commonly
|
|
||||||
done using sshd, but you can also use httpd if you prefer.
|
|
||||||
|
|
||||||
Gitolite can restrict who can read from (clone/fetch) or write to (push) a
|
|
||||||
repository. It can also restrict who can push to what branch or tag, which is
|
|
||||||
very important in a corporate environment. Gitolite can be installed without
|
|
||||||
requiring root permissions, and with no additional software than git itself
|
|
||||||
and perl. It also has several other neat features described below and
|
|
||||||
elsewhere in the [doc/][docs] directory.
|
|
||||||
|
|
||||||
<a name="_why"></a>
|
<a name="_why"></a>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -6,12 +6,12 @@ http URLs, read [this][http] to install gitolite to support "smart http").
|
||||||
|
|
||||||
In this document:
|
In this document:
|
||||||
|
|
||||||
* <a href="#_Impatient_to_install_">Impatient to install?</a>
|
* <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
|
||||||
* <a href="#_side_note_upgrading">(side note) upgrading</a>
|
* <a href="#_side_note_upgrading">(side note) upgrading</a>
|
||||||
* <a href="#_package_method">package method</a>
|
* <a href="#_package_method">package method</a>
|
||||||
* <a href="#_root_method">root method</a>
|
|
||||||
* <a href="#_non_root_method">non-root 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="#_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="#_troubleshooting">troubleshooting</a>
|
||||||
* <a href="#_important_points_to_note">important points to note</a>
|
* <a href="#_important_points_to_note">important points to note</a>
|
||||||
* <a href="#_naming_conventions_used">naming conventions used</a>
|
* <a href="#_naming_conventions_used">naming conventions used</a>
|
||||||
|
|
@ -30,36 +30,27 @@ In this document:
|
||||||
|
|
||||||
----
|
----
|
||||||
|
|
||||||
<a name="_Impatient_to_install_"></a>
|
<a name="_installing_and_upgrading_gitolite"></a>
|
||||||
|
|
||||||
### Impatient to install?
|
### installing and upgrading gitolite
|
||||||
|
|
||||||
This top section is for the impatient. You might qualify if you can
|
This section tells you how to install/upgrade gitolite, without too much
|
||||||
understand the following:
|
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 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
|
||||||
|
|
||||||
> * a server
|
Gitolite allows 3 methods of install. The two most common are (1) the
|
||||||
> * a "hosting user" on the server (a real Unix userid; we use "git" in
|
**package method**, used if you have a gitolite RPM or a DEB available, and
|
||||||
this document, although RPM/DEB installs use "gitolite")
|
(2) the **non-root method** which is the preferred manual install mode. Less
|
||||||
> * a virtual "admin user" -- the user who sets up gitolite and configures it
|
commonly used is (3) the **root method**, which is useful if you plan to have
|
||||||
> * the admin user's client or workstation, from which he does all his work
|
multiple "hosting users" on the same server.
|
||||||
|
|
||||||
> ----
|
|
||||||
|
|
||||||
If you didn't get all that, or thought you did then ran into problems,
|
|
||||||
beg/borrow some patience and read the rest of this document before trying it
|
|
||||||
again.
|
|
||||||
|
|
||||||
Gitolite allows 3 methods of install:
|
|
||||||
|
|
||||||
* **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
|
|
||||||
|
|
||||||
These install methods are described in detail below. (*Once you finish the
|
These install methods are described in detail below. (*Once you finish the
|
||||||
install, read the [admin document][admin] to administer your gitolite
|
install, read the [admin document][admin] to administer your gitolite
|
||||||
|
|
@ -83,8 +74,9 @@ filename as an argument.
|
||||||
|
|
||||||
#### package method
|
#### package method
|
||||||
|
|
||||||
(Unlike the rest of this document, this specific method uses "gitolite" as the
|
(Unlike in the rest of this document, we use "gitolite" as the "hosting user"
|
||||||
"hosting user" instead of "git", because that is what the RPM/DEB creates).
|
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*:
|
On your *workstation*:
|
||||||
|
|
||||||
|
|
@ -105,45 +97,14 @@ On your *workstation*:
|
||||||
|
|
||||||
git clone gitolite@server:gitolite-admin
|
git clone gitolite@server:gitolite-admin
|
||||||
|
|
||||||
<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="_non_root_method"></a>
|
<a name="_non_root_method"></a>
|
||||||
|
|
||||||
#### non-root method
|
#### non-root method
|
||||||
|
|
||||||
**IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this 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, just in
|
you had better know the password to the hosting user on the server, or be able
|
||||||
case you manage to lock yourself out by messing with the keys.
|
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
|
**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
|
you're interested. (That tutorial is by someone else but it's nice enough for
|
||||||
|
|
@ -204,6 +165,38 @@ There are many, many ways to skin this cat; here's one way:
|
||||||
|
|
||||||
Now save the file.
|
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>
|
<a name="_troubleshooting"></a>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue