Sectionize chapter 4

Author: ben

book/04-git-server/1-git-server.asc

@@ -0,0 +1,55 @@
+[[_generate_ssh_key]]
+=== Generating Your SSH Public Key
+
+(((SSH keys)))
+That being said, many Git servers authenticate using SSH public keys.
+In order to provide a public key, each user in your system must generate one if they don’t already have one.
+This process is similar across all operating systems.
+First, you should check to make sure you don’t already have a key.
+By default, a user’s SSH keys are stored in that user’s `~/.ssh` directory.
+You can easily check to see if you have a key already by going to that directory and listing the contents:
+
+[source,shell]
+----
+$ cd ~/.ssh
+$ ls
+authorized_keys2  id_dsa       known_hosts
+config            id_dsa.pub
+----
+
+You’re looking for a pair of files named something like `id_dsa` or `id_rsa` and a matching file with a `.pub` extension.
+The `.pub` file is your public key, and the other file is your private key.
+If you don’t have these files (or you don’t even have a `.ssh` directory), you can create them by running a program called `ssh-keygen`, which is provided with the SSH package on Linux/Mac systems and comes with the MSysGit package on Windows:
+
+[source,shell]
+----
+$ ssh-keygen
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/schacon/.ssh/id_rsa):
+Created directory '/home/schacon/.ssh'.
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /home/schacon/.ssh/id_rsa.
+Your public key has been saved in /home/schacon/.ssh/id_rsa.pub.
+The key fingerprint is:
+d0:82:24:8e:d7:f1:bb:9b:33:53:96:93:49:da:9b:e3 [email protected]
+----
+
+First it confirms where you want to save the key (`.ssh/id_rsa`), and then it asks twice for a passphrase, which you can leave empty if you don’t want to type a password when you use the key.
+
+Now, each user that does this has to send their public key to you or whoever is administrating the Git server (assuming you’re using an SSH server setup that requires public keys).
+All they have to do is copy the contents of the `.pub` file and e-mail it.
+The public keys look something like this:
+
+[source,shell]
+----
+$ cat ~/.ssh/id_rsa.pub
+ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAklOUpkDHrfHY17SbrmTIpNLTGK9Tjom/BWDSU
+GPl+nafzlHDTYW7hdI4yZ5ew18JH4JW9jbhUFrviQzM7xlELEVf4h9lFX5QVkbPppSwg0cda3
+Pbv7kOdJ/MTyBlWXFCR+HAo3FXRitBqxiX1nKhXpHAZsMciLq8V6RjsNAQwdsdMFvSlVK/7XA
+t3FaoJoAsncM1Q9x5+3V0Ww68/eIFmb1zuUFljQJKprrX88XypNDvjYNby6vw/Pb0rwert/En
+mZ+AW4OZPnTPI89ZPmVMLuayrD2cE86Z/il8b+gw3r3+1nKatmIkjn2so1d01QraTlMqVSsbx
+NrRFi9wrf+M7Q== [email protected]
+----
+
+For a more in-depth tutorial on creating an SSH key on multiple operating systems, see the GitHub guide on SSH keys at https://help.github.com/articles/generating-ssh-keys[].

book/04-git-server/sections/generating-ssh-key.asc

@@ -0,0 +1,64 @@
+=== Git Daemon
+
+(((serving repositories, git protocol)))
+Next we'll set up a daemon serving repositories over the ``Git'' protocol. This is common choice for fast, unauthenticated access to your Git data. Remember that since it's not an authenticated service, anything you serve over this protocol is public within it's network.
+
+If you’re running this on a server outside your firewall, it should only be used for projects that are publicly visible to the world.
+If the server you’re running it on is inside your firewall, you might use it for projects that a large number of people or computers (continuous integration or build servers) have read-only access to, when you don’t want to have to add an SSH key for each.
+
+In any case, the Git protocol is relatively easy to set up.
+Basically, you need to run this command in a daemonized manner:(((git commands, daemon)))
+
+[source,shell]
+----
+git daemon --reuseaddr --base-path=/opt/git/ /opt/git/
+----
+
+`--reuseaddr` allows the server to restart without waiting for old connections to time out, the `--base-path` option allows people to clone projects without specifying the entire path, and the path at the end tells the Git daemon where to look for repositories to export.
+If you’re running a firewall, you’ll also need to punch a hole in it at port 9418 on the box you’re setting this up on.
+
+You can daemonize this process a number of ways, depending on the operating system you’re running.
+On an Ubuntu machine, you can use an Upstart script.
+So, in the following file
+
+[source,shell]
+----
+/etc/event.d/local-git-daemon
+----
+
+you put this script:
+
+[source,shell]
+----
+start on startup
+stop on shutdown
+exec /usr/bin/git daemon \
+    --user=git --group=git \
+    --reuseaddr \
+    --base-path=/opt/git/ \
+    /opt/git/
+respawn
+----
+
+For security reasons, it is strongly encouraged to have this daemon run as a user with read-only permissions to the repositories – you can easily do this by creating a new user 'git-ro' and running the daemon as them.
+For the sake of simplicity we’ll simply run it as the same 'git' user that Gitosis is running as.
+
+When you restart your machine, your Git daemon will start automatically and respawn if it goes down.
+To get it running without having to reboot, you can run this:
+
+[source,shell]
+----
+initctl start local-git-daemon
+----
+
+On other systems, you may want to use `xinetd`, a script in your `sysvinit` system, or something else – as long as you get that command daemonized and watched somehow.
+
+Next, you have to tell Git which repositories to allow unauthenticated Git server-based access to. You can do this in each repository by creating a file name `git-daemon-export-ok`.
+
+[source,shell]
+----
+$ cd /path/to/project.git
+$ touch git-daemon-export-ok
+----
+
+The presence of that file tells Git that it’s OK to serve this project without authentication.

book/04-git-server/sections/git-daemon.asc

@@ -0,0 +1,98 @@
+=== Getting Git on a Server
+
+Now we'll cover setting up a Git service running these protocols on your own server.
+
+[NOTE]
+====
+Here we'll be demonstrating the commands and steps needed to do basic installations on a Linux based server, though it's also possible to run these services on Mac or Windows servers too.
+Actually setting up a production server within your infrastructure will certainly entail differences in security measures or operating system tools, but hopefully this will give you the general idea of what's involved.
+====
+
+In order to initially set up any Git server, you have to export an existing repository into a new bare repository – a repository that doesn’t contain a working directory.
+This is generally straightforward to do.
+In order to clone your repository to create a new bare repository, you run the clone command with the `--bare` option.(((git commands, clone, bare)))
+By convention, bare repository directories end in `.git`, like so:
+
+[source,shell]
+----
+$ git clone --bare my_project my_project.git
+Cloning into bare repository 'my_project.git'...
+done.
+----
+
+You should now have a copy of the Git directory data in your `my_project.git` directory.
+
+This is roughly equivalent to something like
+
+[source,shell]
+----
+$ cp -Rf my_project/.git my_project.git
+----
+
+There are a couple of minor differences in the configuration file; but for your purpose, this is close to the same thing.
+It takes the Git repository by itself, without a working directory, and creates a directory specifically for it alone.
+
+==== Putting the Bare Repository on a Server
+
+Now that you have a bare copy of your repository, all you need to do is put it on a server and set up your protocols.
+Let’s say you’ve set up a server called `git.example.com` that you have SSH access to, and you want to store all your Git repositories under the `/opt/git` directory.
+Assuming that `/opt/git` exists on that server, you can set up your new repository by copying your bare repository over:
+
+[source,shell]
+----
+$ scp -r my_project.git [email protected]:/opt/git
+----
+
+At this point, other users who have SSH access to the same server which has read-access to the `/opt/git` directory can clone your repository by running
+
+[source,shell]
+----
+$ git clone [email protected]:/opt/git/my_project.git
+----
+
+If a user SSHs into a server and has write access to the `/opt/git/my_project.git` directory, they will also automatically have push access.
+
+Git will automatically add group write permissions to a repository properly if you run the `git init` command with the `--shared` option.(((git commands, init, bare)))
+
+[source,shell]
+----
+$ ssh [email protected]
+$ cd /opt/git/my_project.git
+$ git init --bare --shared
+----
+
+You see how easy it is to take a Git repository, create a bare version, and place it on a server to which you and your collaborators have SSH access.
+Now you’re ready to collaborate on the same project.
+
+It’s important to note that this is literally all you need to do to run a useful Git server to which several people have access – just add SSH-able accounts on a server, and stick a bare repository somewhere that all those users have read and write access to.
+You’re ready to go – nothing else needed.
+
+In the next few sections, you’ll see how to expand to more sophisticated setups.
+This discussion will include not having to create user accounts for each user, adding public read access to repositories, setting up web UIs, using the Gitosis tool, and more.
+However, keep in mind that to collaborate with a couple of people on a private project, all you _need_ is an SSH server and a bare repository.
+
+==== Small Setups
+
+If you’re a small outfit or are just trying out Git in your organization and have only a few developers, things can be simple for you.
+One of the most complicated aspects of setting up a Git server is user management.
+If you want some repositories to be read-only to certain users and read/write to others, access and permissions can be a bit more difficult to arrange.
+
+===== SSH Access
+
+(((serving repositories, SSH)))
+If you have a server to which all your developers already have SSH access, it’s generally easiest to set up your first repository there, because you have to do almost no work (as we covered in the last section).
+If you want more complex access control type permissions on your repositories, you can handle them with the normal filesystem permissions of the operating system your server runs.
+
+If you want to place your repositories on a server that doesn’t have accounts for everyone on your team whom you want to have write access, then you must set up SSH access for them.
+We assume that if you have a server with which to do this, you already have an SSH server installed, and that’s how you’re accessing the server.
+
+There are a few ways you can give access to everyone on your team.
+The first is to set up accounts for everybody, which is straightforward but can be cumbersome.
+You may not want to run `adduser` and set temporary passwords for every user.
+
+A second method is to create a single 'git' user on the machine, ask every user who is to have write access to send you an SSH public key, and add that key to the `~/.ssh/authorized_keys` file of your new 'git' user.
+At that point, everyone will be able to access that machine via the 'git' user.
+This doesn’t affect the commit data in any way – the SSH user you connect as doesn’t affect the commits you’ve recorded.
+
+Another way to do it is to have your SSH server authenticate from an LDAP server or some other centralized authentication source that you may already have set up.
+As long as each user can get shell access on the machine, any SSH authentication mechanism you can think of should work.

book/04-git-server/sections/git-on-a-server.asc

@@ -0,0 +1,132 @@
+=== GitLab
+
+(((serving repositories, GitLab)))(((GitLab)))
+GitWeb is pretty simplistic though.
+If you're looking for a more modern, fully featured Git server, there are some several open source solutions out there that you can install instead.
+As GitLab is one of the more popular ones, we'll cover installing and using it as an example.
+This is a bit more complex than the GitWeb option and likely requires more maintainance, but it is a much more fully featured option.
+
+==== Installation
+
+GitLab is a database-backed web application, so its installation is a bit more involved than some other git servers.
+Fortunately, this process is very well-documented and supported.
+
+There are a few methods you can pursue to install GitLab.
+To get something up and running quickly, you can download a virtual machine image or a one-click installer from https://bitnami.com/stack/gitlab[], and tweak the configuration to match your particular environment.(((bitnami)))
+One nice touch Bitnami has included is the login screen (accessed by typing alt-→); it tells you the IP address and default username and password for the installed GitLab.
+
+[[bitnami]]
+.The Bitnami GitLab virtual machine login screen.
+image::images/bitnami.png[The Bitnami GitLab virtual machine login screen.]
+
+For anything else, follow the guidance in the GitLab Community Edition readme, which can be found at https://gitlab.com/gitlab-org/gitlab-ce/tree/master[].
+There you'll find assistance for installing GitLab using Chef recipes, a virtual machine on Digital Ocean, and RPM and DEB packages (which, as of this writing, are in beta).
+There's also ``unofficial'' guidance on getting GitLab running with non-standard operating systems and databases, a fully-manual installation script, and many other topics.
+
+==== Administration
+
+GitLab's administration interface is accessed over the web.
+Simply point your browser to the hostname or IP address where GitLab is installed, and log in as an admin user.
+The default username is `[email protected]`, and the default password is `5iveL!fe` (which you will be prompted to change as soon as you enter it).
+Once logged in, click the ``Admin area'' icon in the menu at the top right.
+
+[[gitlab_menu]]
+.The ``Admin area'' item in the GitLab menu.
+image::images/gitlab-menu.png[The ``Admin area'' item in the GitLab menu.]
+
+===== Users
+
+Users in GitLab are accounts that correspond to people.
+User accounts don't have a lot of complexity; mainly it's a collection of personal information attached to login data.
+Each user account comes with a *namespace*, which is a logical grouping of projects that belong to that user.
+If the user +jane+ had a project named +project+, that project's url would be http://server/jane/project[].
+
+[[gitlab_users]]
+.The GitLab user administration screen.
+image::images/gitlab-users.png[The GitLab user administration screen.]
+
+Removing a user can be done in two ways.
+``Blocking'' a user prevents them from logging into the GitLab instance, but all of the data under that user's namespace will be preserved, and commits signed with that user's email address will still link back to their profile.
+
+``Destroying'' a user, on the other hand, completely removes them from the database and filesystem.
+All projects and data in their namespace is removed, and any groups they own will also be removed.
+This is obviously a much more permanent and destructive action, and its uses are rare.
+
+[[_gitlab_groups_section]]
+===== Groups
+
+A GitLab group is an assemblage of projects, along with data about how users can access those projects.
+Each group has a project namespace (the same way that users do), so if the group +training+ has a project +materials+, its url would be http://server/training/materials[].
+
+[[gitlab_groups]]
+.The GitLab group administration screen.
+image::images/gitlab-groups.png[The GitLab group administration screen.]
+
+Each group is associated with a number of users, each of which has a level of permissions for the group's projects and the group itself.
+These range from ``Guest'' (issues and chat only) to ``Owner'' (full control of the group, its members, and its projects).
+The types of permissions are too numerous to list here, but GitLab has a helpful link on the administration screen.
+
+===== Projects
+
+A GitLab project roughly corresponds to a single git repository.
+Every project belongs to a single namespace, either a user or a group.
+If the project belongs to a user, the owner of the project has direct control over who has access to the project; if the project belongs to a group, the group's user-level permissions will also take effect.
+
+Every project also has a visibility level, which controls who has read access to that project's pages and repository.
+If a project is _Private_, the project's owner must explicitly grant access to specific users.
+An _Internal_ project is visible to any logged-in user, and a _Public_ project is visible to anyone.
+Note that this controls both git ``fetch'' access as well as access to the web UI for that project.
+
+===== Hooks
+
+GitLab includes support for hooks, both at a project or system level.
+For either of these, the GitLab server will perform an HTTP POST with some descriptive JSON whenever relevant events occur.
+This is a great way to connect your git repositories and GitLab instance to the rest of your development automation, such as CI servers, chat rooms, or deployment tools.
+
+==== Basic Usage
+
+The first thing you'll want to do with GitLab is create a new project.
+This is accomplished by clicking the ``+'' icon on the toolbar.
+You'll be asked for the project's name, which namespace it should belong to, and what its visibility level should be.
+Most of what you specify here isn't permanent, and can be re-adjusted later through the settings interface.
+Click ``Create Project'', and you're done.
+
+Once the project exists, you'll probably want to connect it with a local Git repository.
+Each project is accessible over HTTPS or SSH, either of which can be used to configure a Git remote.
+The URLs are visible at the top of the project's home page.
+For an existing local repository, this command will create a remote named `gitlab` to the hosted location:
+
+[source,shell]
+----
+$ git remote add gitlab https://server/namespace/project.git
+----
+
+If you don't have a local copy of the repository, you can simply do this:
+
+[source,shell]
+----
+$ git clone https://server/namespace/project.git
+----
+
+The web UI provides access to several useful views of the repository itself.
+Each project's home page shows recent activity, and links along the top will lead you to views of the project's files and commit log.
+
+==== Working Together
+
+The simplest way of working together on a GitLab project is by giving another user direct push access to the git repository.
+You can add a user to a project by going to the ``Members'' section of that project's settings, and associating the new user with an access level (the different access levels are discussed a bit in <<_gitlab_groups_section>>).
+By giving a user an access level of ``Developer'' or above, that user can push commits and branches directly to the repository with impunity.
+
+Another, more decoupled way of collaboration is by using merge requests.
+This feature enables any user that can see a project to contribute to it in a controlled way.
+Users with direct access can simply create a branch, push commits to it, and open a merge request from their branch back into `master` or any other branch.
+Users who don't have push permissions for a repository can ``fork'' it (create their own copy), push commits to _that_ copy, and open a merge request from their fork back to the main project.
+This model allows the owner to be in full control of what goes into the repository and when, while allowing contributions from untrusted users.
+
+Merge requests and issues are the main units of long-lived discussion in GitLab.
+Each merge request allows a line-by-line discussion of the proposed change (which supports a lightweight kind of code review), as well as a general overall discussion thread.
+Both can be assigned to users, or organized into milestones.
+
+This section has focused mainly on the Git-related parts of GitLab, but it's a fairly mature system, and provides many other features that can help your team work together.
+These include project wikis, discussion ``walls'', and system maintenance tools.
+One benefit to GitLab is that, once the server is set up and running, you'll rarely need to tweak a configuration file or access the server via SSH; most administration and general usage can be accomplished through the in-browser interface.