Installing GitWeb on FreeNAS

Learn how to install GitWeb to browse the repositories on your server. Build the Git package from the Ports collection to install GitWeb on an Apache server. Optionally, configure access over HTTPS and LDAP authentication.

Note: I recently moved my Git server to Gitea. To learn how to install Gitea, see Installing a Gitea server on FreeBSD.

The following screenshot shows GitWeb displaying two repositories:

GitWeb screenshot

Preparing the jail

The instructions in this post host the app server in a jail on FreeBSD. To learn why we use jails for this purpose, check the Application server section of our self-hosted architecture post.

In this section, you’ll perform the following tasks:

  • Create a jail.
  • Configure networking on the jail.
  • Install the prerequisite packages.

Run the commands from a session in your FreeBSD host.

To create a jail:

  1. Fetch or update the release version of FreeBSD for jail usage: 
    iocage fetch --release 11.3-RELEASE
  2. Create a jail named gitweb: 
    iocage create --name gitweb --release 11.3-RELEASE

To configure networking on the jail:

  1. Configure the IP address. The following example sets the IP address to 192.168.1.123 using a subnet mask of 24 bits on the em0 interface. The command uses the CIDR notation. 
    iocage set ip4_addr="em0|192.168.1.123/24" gitweb
  2. Configure the default router. The following example sets the default router to 192.168.1.1: 
    iocage set defaultrouter=192.168.1.1 gitweb

Start the jail and open a session to complete the rest of the tasks in this section:

iocage start gitweb
iocage console gitweb

Install the following packages:

  • apache24
  • mod_php73
  • portmaster
pkg update
pkg install --yes apache24 mod_php73 portmaster

Installing GitWeb from Ports

GitWeb is not included by default in the Git package. To get the GitWeb binaries, you need to install Git from the Ports collection.

  1. Download and extract the Ports Collection: 
    portsnap fetch extract update
  2. Build and install the Git package the GitWeb binaries: 
    portmaster -m GITWEB="on" /usr/ports/devel/git

    The build system shows the configuration prompts for the Git package and its dependencies, but the GitWeb option is preselected. Accepting the default options work well for most installations.

Configuring the web service

  1. Copy the example GitWeb directory that is included with the Git package: 
    cp -R /usr/local/share/examples/git/gitweb /usr/local/www/gitweb
  2. In the /usr/local/etc/apache24/httpd.conf file:
    • Uncomment the LoadModule directives to enable the CGI modules by removing the leading # character: 
      <IfModule !mpm_prefork_module>
    LoadModule cgid_module libexec/apache24/mod_cgid.so
</IfModule>
<IfModule mpm_prefork_module>
    LoadModule cgi_module libexec/apache24/mod_cgi.so
</IfModule>
    • Replace the following DocumentRoot and Directory entries: 
      DocumentRoot "/usr/local/www/apache24/data"
<Directory "/usr/local/www/apache24/data">
    ...
</Directory>

      with the entries of your GitWeb directory:

      DocumentRoot "/usr/local/www/gitweb"
<Directory "/usr/local/www/gitweb">
    AuthType None
    Options +FollowSymLinks +ExecCGI
    DirectoryIndex gitweb.cgi
    AddHandler cgi-script .cgi .pl
    Satisfy Any
    Allow from all
</Directory>
  3. Configure service start: 
    sysrc apache24_enable="yes"
  4. Restart the web server: 
    service apache24 onerestart

Create the common root directory

The repositories must be stored in a common root directory, which by default is located in the /pub/git directory. To create the /pub/git directory:

mkdir -p /pub/git

If you followed our post about installing a Git server on FreeNAS and chose the option to store the repositories on a ZFS dataset, then you can just mount the dataset on /pub/git by running the following command from a FreeNAS shell.

iocage fstab gitweb --add /mnt/tank/repos /pub/git nullfs ro 0 0

Otherwise, create a repository to test the installation:

  1. Create a repository: 
    mkdir -p /pub/git/repo1
cd /pub/git/repo1
git init
  2. Create a commit in the repository: 
    touch file1
git add file1
git commit -m "Adds file1 to repo"

Open a browser and go to http://192.168.1.123 to check the GitWeb interface.

Configure access over HTTPS

To configure access over HTTPS, you need an SSL certificate, such as the ones provided by Let’s Encrypt.

  1. Copy the ca, crt, and key files of your certificate to a folder in the jail.
  2. By default, any .conf file in the Includes folder is added to the Apache configuration. Create the /usr/local/etc/apache24/Includes/my-conf.conf file with the following contents: 
    LoadModule ssl_module libexec/apache24/mod_ssl.so
LoadModule socache_shmcb_module libexec/apache24/mod_socache_shmcb.so
Listen 443
<VirtualHost *:443>
  DocumentRoot "/usr/local/www/gitweb"
  ServerName gitweb.example.org:443
  SSLEngine on
  SSLCertificateFile      /path/to/certificate.crt
  SSLCertificateKeyFile   /path/to/certificate.key
  SSLCertificateChainFile /path/to/certificate.ca
</VirtualHost>
  3. Restart the web server: 
    service apache24 onerestart

Configure LDAP authentication

You can configure Apache to validate the users against an LDAP directory, such as OpenLDAP. If you configure authentication using this method, make sure to enable HTTPS because the credentials are transmitted over the network in plain text.

This section assumes you already have a working LDAP server. For more information, check the Installing an OpenLDAP server tutorial.

Apache doesn’t include the modules required for LDAP authentication by default. To get the modules, you need to install Apache from the Ports collection. To install Apache from the Ports collection:

  1. Remove the apache24 package: 
    pkg delete apache24
  2. Install the apr1 package. Make sure to select the LDAP option from the first dialog: 
    portmaster /usr/ports/devel/apr1
  3. Install the apache24 package. Make sure to select the AUTHNZ_LDAP and LDAP options from the first dialog: 
    portmaster /usr/ports/www/apache24

In /usr/local/etc/apache24/httpd.conf, configure the web server to use the LDAP modules and provide your LDAP server parameters:

  1. To enable the LDAP modules, add the following LoadModule directives: 
    LoadModule ldap_module libexec/apache24/mod_ldap.so
LoadModule authnz_ldap_module libexec/apache24/mod_authnz_ldap.so
  2. Replace the Directory element added in the Configuring the web service section with the following: 
    <Directory "/usr/local/www/gitweb">
  AuthType BasicAuth
  Name "LDAP authentication required"
  AuthBasicProvider ldap
  AuthLDAPURL ldap://ldapserver.example.org/ou=users,dc=example,dc=org?uid STARTTLS
  AuthLDAPBindDN [email protected],ou=services,dc=example,dc=org
  AuthLDAPBindPassword gitweb_service_password
  Options +FollowSymLinks +ExecCGIDirectoryIndex gitweb.cgi
  AddHandler cgi-script .cgi .pl
  Require valid-user
</Directory>
  3. Restart the web server: 
    service apache24 onerestart

    Let’s review the new parameters in this configuration:

    • AuthType: Selects that method that is used to authenticate the user. TheBasicAuth method sends the credentials through the network in plain text. This is the reason why you must configure HTTPS before enabling LDAP authentication.
    • AuthBasicProvider: Selects the provider to use with basic authentication. In this case, LDAP.
    • AuthLDAPURL: This parameter configures several options:
      • Protocol: Depending on your LDAP service, you can select ldap or ldaps.
      • LDAP URL: The URL of your LDAP server. In the example, ldapserver.example.org.
      • Container where to look for users. In this case, ou=users,dc=example,dc=org.
      • Attribute to match with the username entered in the login field. In this case, uid. It’s advised to use a field that is unique in the LDAP directory, using an attribute that can be shared in multiple accounts, such as cn can lead to authentication issues.
      • Connection type. In this example, STARTTLS, which establishes a secure connection on the default LDAP port (389). You can establish an unsecure connection on the default LDAP port using the NONE option.
    • AuthLDAPBindDN: The account used to bind to and query the LDAP directory.
    • AuthLDAPBindPassword: The password of the account used to bind to the LDAP directory.
    • Require: Provides the authorization part of the process. In this case, valid-user accepts any user in the LDAP directory.