+----------------------------------------------------------------------
| Getting started with Game of Trees on pkgsrc
+----------------------------------------------------------------------

To use the Game of Trees daemon to host git repositoties, a few
manual setup steps are required.

| NOTE: this tutorial was originally written for Debian by Tobias
| Heider (@tobhe), to whom all credit goes. This is a modified
| version adjusted for pkgsrc/NetBSD, with minor additions.

Below is an example for setting up read only anonymous access to a
clone of the upstream got repository.

First we need to check out the got source code on our host machine.

    ----------------------------------------------------------------
    # Create git directory
    $ mkdir -p /var/git
    $ cd /var/git

    # Clone the repository you are planning to serve with got
    $ got clone ssh://anonymous@got.gameoftrees.org/got.git

    # Alternatively you can use git
    $ git clone --bare ssh://anonymous@got.gameoftrees.org/got.git

    # Make sure the gotd user can access the directory
    $ chown -R _gotd:_gotd /var/git
    ----------------------------------------------------------------

For our example, we need to create an anonymous ssh login user and
group with an empty password to allow everyone read only access.
For a more restricted setup, it is also possible to create a developer
group and users with pre-shared ssh keys.

    ----------------------------------------------------------------
    # Add anonymous user for ssh login
    $ groupadd anonymous
    $ useradd -g anonymous -c "Anonymous GoT server login" \
      -d /nonexistent -s /usr/pkg/bin/gotsh anonymous
    ----------------------------------------------------------------

It is strongly recommended to harden the anonymous user's sshd config to
make sure they can only run their gotsh shell. In our case, password
authentication and empty passwords need to be allowed explicitly.

    /etc/ssh/sshd_config:
    ================================================================
    Match User anonymous
	DisableForwarding yes
	PermitTTY no
	PasswordAuthentication yes
	PermitEmptyPasswords yes
    ================================================================

Now, modify /usr/pkg/etc/gotd.conf to point the daemon to our git
repository and allow read-only access for the anonymous user:

    /usr/pkg/etc/gotd.conf:
    ================================================================
    # Run as the default user
    user _gotd

    # ssh://anonymous@example.com/got
    repository "got" {
            path "/var/git/got.git"
            permit ro anonymous
    }
    ================================================================

See the gotd.conf(5) man page to learn more about gotd configuration. 

gotd requires the `git-receive-pack' and `git-upload-pack' commands to
invoke gotsh. However, git already provides these commands as
symbolic links to the git binary. To prevent conflicting names, GoT
comes with the gitwrapper(1) utility, which acts similarly to
mailwrapper(8) for MTAs, invoking the correct git server (git or got
daemon) for the right repository, depending on the chosen policy.

For this to work, the aforementioned commands need to be symlinked to
gitwrapper under /usr/pkg/bin: 

    ---------------------------------------------------------------
    $ cd /usr/pkg/bin
    $ ln -sf gitwrapper git-upload-pack
    $ ln -sf gitwrapper git-receive-pack
    ---------------------------------------------------------------

In such way, any Git repository listed in @PKG_SYSCONFDIR/gotd.conf
will be automatically served by gotd, while any Git repository not
listed in @PKG_SYSCONFDIR/gotd.conf shall be served by git, allowing 
a peaceful co-existence of gotd and Git.                   

To run the GoT server, import the sample rc.d service script provided
with this package and activate the gotd service:

| NOTE: this assumes an underlying BSD system using rc services

    ----------------------------------------------------------------
    $ cp /usr/pkg/share/examples/rc.d/gotd /etc/rc.d
    $ echo gotd=YES >> /etc/rc.conf
    ----------------------------------------------------------------

Finally, reload the sshd configuration and start the gotd service:

    ----------------------------------------------------------------
    $ service sshd restart
    $ service gotd start 
    ----------------------------------------------------------------

It should now be possible to clone the git repository with:

    ----------------------------------------------------------------
    $ got clone ssh://anonymous@example.com/got
    ----------------------------------------------------------------

You can find more information on how to configure gotsh and gotd in
their respective man pages gotsh(1), gotd(8), and got.conf(5).
