one melo a day

moon indicating dark mode
sun indicating light mode

Turn your DiskStation into a self-hosted Git server

March 05, 2016

One of the things I almost instantly wanted to do after purchasing my DiskStation was to use it as a private Git server. I thought I was in luck when I saw that Synology offers a DSM package for Git, but it turned out this is too basic for my taste. The good thing is, since I now have HTTPS accessible Tomcat running on my DiskStation I can easily install and run GitBlit. So let’s turn our DiskStation into a private, HTTPS accessible, collaboration friendly Git server!

The Motivation

You might ask yourself: “Why not just use Synolog’s Git Package for DSM?” Well, if you are the only one interacting with your repositories, you are fine with ssh accessing your DiskStation every time you want to create a new repository and like to create shared, bare repositories manually on the command line, feel free to do so. The best guide I could find for that is this one. However, I did not like this solution for several reasons. I do want to collaborate on my repositories and I do want to be able to do so without creating full DSM accounts for every collaborator. I do want to have a GUI both for creating and managing access to my repositories instead of ssh accessing my DiskStation, manually creating the repository and fiddle with file and folder permissions.

My Way to go

So I started to look around and found there are several solutions out there. If you are interested you can check out this comparison of self-hosted web-based Git repository managers. Although GitLab looks like a really good and very popular choice I decided otherwise. Main reason being that the documented installation methods did not really spark any hope that I could get this to run on my DiskStation. GitBlit however looked like an easy deployment of the GitBlit WAR file to Tomcat. It also offers all the features I was looking for. It provides me with a GUI to create repositories and manage access to them. This way my repositories are both private and accessible. So now that you know why I chose GitBlit, read on to see how I managed to set it up and run it on my DiskStation. If you want to follow along, make sure you have Tomcat 7 already running on your DiskStation. In my last post I described how to use a Let’s Encrypt certificate to enable HTTPS for your Tomcat server and linked to a guide I partially used to setup Tomcat on the DiskStation, so make sure to check it out.

Set up GitBlit

Obviously the first thing you want to do is to download the latest GitBlit WAR file from the official website. At this point you could just drop this WAR file into the Tomcat folder on your DiskStation, wait a few seconds for Tomcat to finish the deployment and access GitBlit by URL, which should look something like this (assuming you followed my last post): https://yourDomain:8443/gitblit However there are a few tweaks that will ensure that all your repositories and settings will be persistent across GitBlit redeploys and updates and that all features are working properly. First thing is to set a custom GitBlit baseFolder as Tomcat Context to externalize GitBlit data from its deployment path both for safety and persistence across updates and redeploys as described in the GitBlit WAR installation and setup guide. So access your DiksStation through ssh as root and edit Tomcat’s context.xml file. You can use vi to edit the file. The command should be similar to this one: vi /volume1/@appstore/Tomcat/src/conf/context.xml Inside context.xml file you insert an Environment node within the Context node that looks like this: <Environment name="baseFolder" type="java.lang.String" value="/volume1/@appstore/gitblit" /> If you deploy the GitBlit WAR now, all the configuration files and repositories will go inside the baseFolder you just specified. To ensure all GitBlit generated URLs will work you need to do three things. First add org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true to CATALINA_OPTS. To accomplish this I edited the setenv.sh file located in  /volume1/@appstore/Tomcat7/src/bin/ . Add the following line to it: CATALINA_OPTS=-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true Second ensure your Tomcat connector configuration uses the UTF-8 encoding (which it does if you followed my last post). Check the GitBlit FAQ for these two steps. Third add web.canonicalName to gitblit.Properties - which you can find in the baseFolder you specified earlier - and set it to the URL you use to access GitBlit. It is noteworthy that GitBlit comes with a tickets feature, which is analogous to GitHub/BitBucket Issues+Pull Requests. However this feature is disabled by default and the main reason is that you must choose the persistence backend to use for the tickets. You can choose between persisting to files, branch or to a Redis data store. Check out the documentation to make an informed decision. I decided to use the branch ticket service, so I added the following line to gitblit.properties: tickets.service = com.gitblit.tickets.BranchTicketService At this point I thought I was done, but when starting GitBlit and looking at the Tomcat log I noticed that GitBlit failed to start its git and ssh daemon on my DiskStation, because the ports were already in use. If this is the case for you too, You can easily fix this by adding the settings git.daemonPort and git.sshPort to your gitblit.Properties file inside your basefolder and provide non-default port numbers, to allow GitBlit to run these services. Don’t forget to setup port forwarding and an according firewall rule for the configured git.sshPort to allow usage of the ssh protocol for interaction with your repositories. Now you are finally done! After restarting Tomcat (e.g. with the DSM Package Center) the new settings for Tomcat and GitBlit are applied and you can access your very own GitBlit server using an URL like  https://yourDomain:8443/gitblit .  It is available through HTTPS, just like your Tomcat server is, without the need to configure anything HTTPS related in GitBlit itself. GitBlit will now produce working URLs to interact with your repositories and store everything safely in the defined baseFolder. In my case this is /volume1/@appstore/gitblit , which is persistent even across DSM updates, so there won’t be anything gone missing after you update GitBlit or your DiskStation’s DSM version. So log in with  the default administrator credentials admin / admin and change your admin password, create repositories, set their access policy, create users for collaborators, grant them access to specific repositories and enjoy all of this on your very own self-hosted Git server!

The icing on the cake

In case you plan to deploy further applications on Tomcat, I ask you: Wouldn’t it be nice if you could use the same credentials instead of creating a new user for every application you deploy? By default GitBlit uses a simple users.conf file to store user information inside its baseFolder. But If you want to take this a little step further, instead of using GitBlit’s own users.conf file you can configure GitBlit to use the LDAP authentication provider and thus connect GitBlit to a directory server to handle user authentication. What lucky coincidence that Synology’s Package Center offers a Directory Server package, right? So I hope this was interesting to you and recommend you check back for my next post to find out how to setup Synology Directory Server and connect GitBlit to it!