Gogs, an alternative to Gitlab


tl;dr Gitlab is a great git hosting service, almost as powerful as Github. But, is there something out there that’s comparable to Gitlab/Github, yet simpler to manage ? I think Gogs does the job.


These days, Github has become the preferred platform to host code. With its many great features, ease of use and access, almost all software developers are happily using it.

Also, since Google Code hosting project is closing down, you can expect more projects being driven to it.

But what if you’re writing some Android app, maybe you’re building the next great iOS game or in general, you’re writing some code that you don’t want to be exposed to the general public ?

You could certainly purchase access to private Github repositories, but most certainly you’d rather want to invest your capital in more pressing matters.

This is where software such as Gitlab, and Gogs, come very handy.

They provide a service very similar to Github, with the difference that you can host them in your own servers, even in your own workstation.

Read on for some more insight.


Gitlab is a powerful git service, with features that rival Github itself. It’s a mature project and it’s being continuously updated.


They recently acquired Gitorius (another Github-like service), so you can only assume that the feature set will expand (check the press clip about the acquisition).

Installation has been undoubtedly improved since the ‘manual’ days, which was time-consuming and very error prone.

Now there’s a Linux deb/rpm package available (called the Omnibus), which handles all dependencies and simplifies the process.

Upgrading is a bit more convoluted, especially if you’re coming from a version that’s prior to the last, but all in all, it’s not that complicated.

Nevertheless, you can feel a lot of stuff is going on behind the scenes. You will be running Sidekiq, Unicorn, Nginx, Ruby (plus all its gems) and then Gitlab itself.

Customizing the install is not that simple and if something should go wrong, there are many moving parts, where you would have to go looking for problems.

Enter the One binary

On the other hand, we have Gogs. A single binary is all you need to run it.

It’s built with Go, so you automatically get cross-platform compatibility.

It runs on Windows, Mac, Linux, ARM, etc.


Installation simply requires unzipping the release archive into a chosen folder. That’s it. Upgrading works the same: just unzip the release archive.

That’s the beauty of Go’s binary deployments, you can target multiple platforms at once.

Gogs has a really low footprint, so it’s easy on system resources (it can run on a Raspberry Pi).

You could run it as is, with the default configuration, or do some minimal tweaking.

The default configuration file is located in <install folder>/conf/app.ini, but the documentation suggests to write your changes in <install folder>/custom/conf/app.ini, so that when you upgrade, your customizations are preserved (since conf/app.ini is overwritten).

There are three sensible changes you could consider:

  • Repository location
ROOT = !! this is the location where you want to keep the repositories !!

  • Database location
PATH = !! this is the location of your database (sqlite3 by default) !!

  • Public key to enable commit over ssh


Note that currently, you need to run an ssh server (openssh will do fine), the same as Gitlab.


Let’s compare both products to see how they match up in terms of feature set. I’ll throw in Github, as a reference.





Dashboard & File Browseryesyesyes
Issue Tracking, Milestones & Commit keywordsyesyesyes
Organizations supportyesyesyes
Code Reviewnoyesyes
Code Snippetsnoyesyes
Web Hooksyesyesyes
Git Hooksyes* Enterprise* Enterprise
LDAP Loginyesyesyes
LDAP Group Syncno* Enterprise* Enterprise
Branded Login Pageno* Enterprise* Enterprise
PlatformCross-PlatformLinux* Virtual Machine
Resource UsageLowMedium/HighMedium/High

Code Review (and pull requests) is arguably the most important missing feature. It's at the top of the list among [Gogs Github issues](https://github.com/gogits/gogs/issues/5) and Gogs's main developer ([Unknwon](https://github.com/Unknwon)) is working on it.

But all said, you have a very functional private Git host service.

Running a Gogs docker

I previously described how I ‘dockerized’ my home server environment, so it’s only fitting that I would run gogs as a Docker container.

So let’s do it step by step.

I have an apps folder in my server home directory (/home/kayak/apps) and create subfolders per each app I deploy as a Docker container.

Download and unzip the latest version (use the archive that corresponds to your platform)

$ cd /home/kayak/apps
$ wget https://gogs.dn.qbox.me/gogs_v0.5.13_linux_amd64.zip
$ unzip gogs_v0.5.13_linux_amd64.zip
$ rm gogs_v0.5.13_linux_amd64.zip

Optional | Customize the configuration

$ cd gogs
$ mkdir -p custom/conf
$ cd custom/conf
$ nano app.ini
ROOT = !! this is the location where you want to keep the repositories !!

PATH = !! this is the location of your database (sqlite3 by default) !!

NOTE: At this point, you could simply run gogs web and you’d have it running normally, not as docker container.

Let’s create our Dockerfile

$ cd /home/kayak/apps/gogs
$ nano Dockerfile
FROM ubuntu:14.04

ENV DEBIAN_FRONTEND noninteractive

RUN sed 's/main$/main universe multiverse/' -i /etc/apt/sources.list && \
 apt-get update && apt-mark hold initscripts && \
 apt-get install -y sudo openssh-server git && \
 apt-get clean

EXPOSE 22 3000

RUN addgroup --gid 501 kayak && adduser --uid 501 --gid 501 --disabled-password --gecos 'kayak' kayak && adduser kayak sudo

WORKDIR /home/kayak
ENV HOME /home/kayak

ENTRYPOINT ["/home/kayak/boot"]

The Dockerfile is based on the latest Ubuntu server LTS version (14.04).

We then install sudo, openssh and git, expose ports 22 (for ssh) and 3000 (for the gogs web interface).

Additionally, I generally create a user (kayak in this case) with the same uid/gid as my user in my Mac box, to prevent issues with access permissions.

Finally, the boot shell script is called to get things running.

$ touch boot
$ chmod +x boot
$ nano boot

sudo -u kayak -H touch /home/kayak/.ssh/authorized_keys
chmod 700 /home/kayak/.ssh && chmod 600 /home/kayak/.ssh/authorized_keys

# start openssh server

mkdir /var/run/sshd
/usr/sbin/sshd -D &

exec sudo -u kayak /home/kayak/gogs web

What this does is run the ssh daemon and then run gogs, as kayak user (rather than root, which is the default).

Let’s build the image

$ cd /home/kayak/apps/gogs
$ docker build --rm -t apertoire/gogs .

Once the image is built, we can run it with

$ docker run -d --name gogs \
 -v /etc/localtime:/etc/localtime:ro \
 -v /home/kayak/apps/gogs:/home/kayak \
 -p 62723:22 \
 -p 3000:3000 \

You can check the command line to see that it’s running.


Now you can open the web interface, and it will show an install page (for first-time run)


Once you have completed the install, you’ll have a functional Gogs service.



Gogs is a lightweight, easy to set up, cross-platform git hosting service, with features favorably comparable to Gitlab/Github.

It’s not as mature as the other two, but it’s still incredibly capable.

It’s also open source, so you can contribute to improve it.

I replaced my Gitlab installation with Gogs a couple of months ago and haven’t looked back.

I’m hosting 42 repositories and have found performance to be extremely good.

I definitely recommend Gogs as your git self-hosting service.

Final Notes

Hope you found the article interesting.

Please leave your comments here or share on social media.

Sharing is caring!

If you got value from this article, please consider sharing it with your friends and colleagues.