Introduction
Self-hosting your own Git service can seem like a daunting task, but with Gogs, the process becomes much more approachable. Gogs is a lightweight and efficient Git service designed for simplicity and ease of use. In this guide, I’ll walk you through setting up Gogs using Docker, which streamlines the installation and management process significantly. Whether you're a developer looking for more control over your repositories or someone interested in exploring self-hosted solutions, this post will help you get started.
Using Docker to manage Gogs takes a lot of the guesswork out of hosting your Git service. It handles much of the underlying configuration for you, and by running it in a container, you can isolate it from the rest of your system. In this post, I’ll also cover configuring Git to work seamlessly with your Gogs instance, as well as some basic Git commands to help you hit the ground running. The goal here is to make the process as straightforward as possible while still giving you the tools to customize it to your needs.
What I really enjoy about Gogs is how it balances simplicity with functionality. You get all the essential Git features like SSH key support and webhooks, but without the steep learning curve that often comes with self-hosted solutions. Plus, it’s entirely free to use, which makes it a great alternative to services that lock certain features behind a subscription. By the end of this guide, you’ll have a fully functioning Git service that’s ready for use, along with the knowledge to manage it effectively. Let’s dive in!
References
gogs
gogs
Prerequisites
- Internet Connection
- Up-to-date Server
- Proper permissions to run Docker commands
- Docker Setup - Ultimate Docker Guide
Overview
Gogs is a lightweight and easy-to-use Git service that you can host yourself. It’s designed to be painless to set up and run, making it a great choice for anyone who wants to manage their own Git repositories without relying on third-party platforms. By using Docker, getting Gogs up and running is even simpler, as the container handles most of the setup for you.
One of the things I like about Gogs is how straightforward it is. It doesn’t try to overwhelm you with unnecessary features, but it still packs a punch. You get core Git functionality, a clean user interface, and support for things like SSH keys and webhooks. The best part? It’s completely free to use. There aren’t any paid features locked behind a subscription, which is refreshing when compared to other similar services.
Setting up the Docker Container
mkdir -p /data/gogs/storage
chmod 775 -R /data/gogs
chown user:data -R /data/gogs
nano docker-compose.yml
# Use Control+O to save and Control+X to exit
services:
gogs:
image: gogs/gogs:0.13
container_name: gogs
ports:
- "43434:3000"
volumes:
- /data/gogs/storage:/data
depends_on:
- postgres
restart: unless-stopped
networks:
- gogs
postgres:
image: postgres:14
container_name: gogs_postgres
environment:
- POSTGRES_DB=gogs
- POSTGRES_USER=gogs
- POSTGRES_PASSWORD=special-database-password
volumes:
- /data/gogs/postgres:/var/lib/postgresql/data
restart: unless-stopped
networks:
- gogs
networks:
gogs:
driver: bridge
As you can see I elected not to use a SSH port, the reason being is that for whatever reason, my server was intercepting the calls and wanting a public key. No matter what I did I couldn’t get in via SSH. However, HTTPS works surprisingly well.
Git Requirements
Installing Git
Depending on your operating system, git can be installed a few ways. For Windows, you can use the installer, and for MacOS or Linux you can either install from brew or the main repository.
# for MacOS
brew install git
# for linux (debian install)
sudo apt update
sudo apt install git
# for linux (RHEL install)
sudo dnf update -y
sudo dnf install git -y
Configuring Git
To use git with your instance, you will need to set the email and username in your .gitconfig file. I recommend setting it to the email and username of your Gogs service that you registered with. Open up your terminal and do the following:
git config --global user.name "Your Name"
git config --global user.email "youremail@yourdomain.com"
You can confirm the changes have taken effect by doing git config --list in your terminal.
Git Commands
Cloning Git Repo
You can clone a repo, and it will ask you to provide a username and password.
git clone <https://git.example.com/user/test-repo.git>
You can do so with a username and token. You can generate a token through Settings > Application and use the following to access a repository.
git clone <https://<username>:<token>@git.example.com/user/test-repo.git>
Cloning Branches
By default, clone the repo will give you access to all the branches. You can use the following to see all the branches:
git branch -a
Grab a Specific Branch
This will grab a specific branch and make it primary, but it will still grab the other branches.
git clone --branch branch-name remote-repo-url
# or
git clone -b branch-name remote-repo-url
If you want to grab a specific branch and not the others, you can use the following below. This performs the same action, however, this option was introduced in Git 1.7.10 (and later).
git clone -b branch-name --single-branch remote-repo-url
Stage Changes
git add .
Commit Changes
git commit -m "Your commit message"
Push Changes
git push origin branch-name
New Branch
Creating a New Branch Based on the Current HEAD
To create a new branch based on the current HEAD, use the following command. This is the most common way to create a new branch as it starts from your current position in the project.
git checkout -b new-branch-name
# Replacenew-branch-name with your desired branch name.
Creating a New Branch Based on an Existing Branch
To create a new branch based on an existing branch, first, switch to that branch, then create the new branch. Replace existing-branch with the name of the branch you want to base your new branch on, and new-branch-name with the desired new branch name.
git checkout existing-branch
git checkout -b new-branch-name
Creating a New Branch from a Specific Commit
To create a new branch from a specific commit, you need the commit hash. This allows you to branch out from any point in the project's history. Replace new-branch-name with your desired branch name and commit-hash with the hash of the commit from which you want to create the branch.
git checkout -b new-branch-name commit-hash
Creating a New Branch from a Specific Tag
To create a new branch from a specific tag, you can use the tag name. This is useful when you want to branch out from a specific release or version. Replace new-branch-name with your desired branch name and tag-name with the name of the tag.
git checkout -b new-branch-name tag-name
Creating a New Branch from a Remote Branch
To create a new branch from a remote branch, first, fetch the remote branches, then create and track a new branch based on the remote one. Replace new-branch-name with your desired branch name and remote-branch-name with the name of the remote branch.
git fetch origin
git checkout -b new-branch-name origin/remote-branch-name
Creating a New Branch in a Remote Repository
After creating a new branch locally, you need to push it to the remote repository to share it with others. Replace new-branch-name with the name of the branch you created.
git push origin new-branch-name
Fetching New Data
# grabs new from the branch
git pull origin branch-name
# grabs all updates from all the branches
git fetch origin
Reverse Proxy
The nice thing about Gogs is that it’s real simple to setup behind a reverse proxy. You can do this with Nginx Proxy Manager or anything else you may have running.
Conclusion
Setting up your own Git service with Gogs using Docker is a manageable and rewarding process. By following the steps outlined in this guide, you can create a self-hosted environment that gives you full control over your repositories without the complexity of other platforms. Docker simplifies the setup by handling much of the configuration for you, and Gogs itself offers the core Git features you need with a lightweight, user-friendly interface. Whether it’s creating repositories, managing branches, or configuring Git to work seamlessly with your instance, this guide provides the foundation to get you started with confidence.
Throughout this post, I aimed to address not just the technical setup but also the practical aspects of using Gogs, from installing Git to managing branches and troubleshooting common issues. Self-hosting your Git service does require some effort, but the benefits of having a customizable, private solution make it worth the investment. I hope this guide has given you the tools and knowledge to implement Gogs effectively, and that you feel equipped to explore its full potential. If you’re ready to take control of your version control system, Gogs is a solid choice that balances simplicity and functionality.
Full Disclosure
Most of this article is comprised of facts and opinions. AI (specifically Grok and Notion AI) was used in the creation of this post. The featured background image was created by andyoneru and is available on Unsplash. I added a blur and a gradient overlay with some text. The following images have been pulled or screenshotted from the respective websites/applications. I do not own this content.
