Quick Links

Don't want to push your code to a hosted Git repository? Then run your own Git server in-house. Gogs is the easiest way to do that. Here's how to set it up.

The Problem With Cloud-Hosted Repositories

Without a doubt, Git is the preeminent version control system. Even with single-developer projects, Git provides value and benefit because of its versioning functionality. For multi-developer projects, Git brings another dimension entirely. With a central, remote repository Git enables a collaborative capability that will transform the way your development teams view version control.

Related: What Is GitHub, and What Is It Used For?

That's why services like GitHubGitLab, and BitBucket exist, and why they've seen such uptake and growth. GitHub alone hosts over 200 million repositories. But cloud-hosted repositories don't suit everyone. Most of them charge to host private repositories. Some of them impose storage limits, user limits, or data transfer limits on free accounts.

Even if your usage and team size fits within the restrictions of the free accounts, or even if you're willing to pay for a commercial license, you may just not feel comfortable storing your code base in the cloud.

The alternative is to host your own Git server either locally on your own network, or privately accessible in your own private cloud. Setting up a Git server that provides a web interface with the look, feel, and options that GitHub and friends have made so popular used to require a certain degree of technical skill. That's where Gogs comes in.

What Is Gogs?

Gogs is a relatively new project, written in Go, that delivers an easy-to-install, yet fully-featured Git instance. There are no limits to team size, storage, or anything else.

Even if you're a hobbyist programmer, using Gogs as a Git service on your local network lets you store a copy of your code away from your development machine. When you---or someone else---want to work on a different or new computer, you simply clone a repository from your Gogs server just like you would from GitHub.

If you're going to use Gogs frequently, you'll probably find it convenient to add it to the startup applications of the computer it's running on.

Related: How to Run a Linux Program at Startup with systemd

How to Install Gogs

To install Gogs, you download the appropriate archive file, unzip it, and run the main binary. You fill out a few forms, and Gogs initializes your repository and adds you as the admin user. You can then browse to your Gogs instance and add users and create repositories.

Gogs uses a database for its back-end storage. It supports MySQL, MariaDBPostgreSQL, and TiDB. If you want to use one of these powerful database engines, you must locate and install it yourself, before installing Gogs. For smaller teams, you can use SQLite3. If you opt for SQLite3, it's installed for you. Of course, you'll need to have

        git
    

installed, too.

Download the appropriate binary.

  • For most modern Linux distributions, download the "Linux amd64" file.
  • If you are using a 32-bit version of Linux, download the "Linux 386" file.
  • If you're installing onto a Raspberry Pi 2 or earlier, download the "Linux armv7" file.
  • If you're installing onto a Raspberry Pi 3, 3+, or later, download the "Linux armv8" file.
  • If you're using an Intel Mac, download the "macOS amd64" file.
  • For an Apple Silicon Mac, download the "macOS arm64" file.

We downloaded the "Linux amd64" ZIP file, for installation onto a 64-bit computer with Ubuntu 22.10. The file is small---only about 25MB---so don't be surprised if it downloads very quickly. That's normal.

Locate the file in your file system. If you've kept your browser's default download location, the file will probably be in your "~/Downloads" directory. Right-click it and select "Extract" from the context menu. Some file browsers might use "Extract Here" instead.

Right-click context menu with "Extract" option highlighted

A directory is extracted from the ZIP file. It's named after the downloaded file. In our case, it was called "gogs_0.11.91_linux_amd64."

The extracted directory, named after the downloaded file

Double-click the extracted directory and you'll see another directory called "gogs."

The gogs directory

Double-click the "gogs" directory. You'll see the Gogs files and directories. Right-click in the file browser window and select "Open in Terminal" from the context menu.

Right-click context menu with "open in Terminal" option highlighted

To start your Gogs instance, type this command:

./gogs web

Starting the gogs Git server

Gogs launches, and tells you it is listening on port 3000.

Connect to your Gogs server by opening a web browser and navigating to the IP address or network name of the computer Gogs is running on. Add ":3000" after the IP address or network name. Don't include any whitespace.

If you're browsing on the computer that Gogs is running on, you can use "localhost" as the machine name, like this "localhost:3000." Our Gogs computer is called "ubuntu-22-10.local", so from a different computer on the same network, the address we need to browse to is "ubuntu-22-10.local:3000", including the port number.

The first time you do this, you'll see the form that captures some initial setup information.

The database selection menu portion of the Gogs configuration screen

The first things we need to do is select "SQLite3" from the "Database Type" drop-down menu and enter your user name in the "Run User" field.

The "Run User" field of the Gogs configuratrion screen

If you want to set up email notifications you'll need to configure a few extra steps. You'll need to relay the emails through a Simple Mail Transfer Protocol (SMTP) mail server that you have permission to use. If you're a Google Gmail user, you can use Google's Gmail SMTP server.

This will require settings on the mail server to allow your account to accept and relay the email. These settings vary from mail server to mail server.

Gogs requires you to enter the following information about your email server.

  • SMTP Host: The address and port of the email server. In our example, this is Google's SMTP server at smtp.gmail.com:587.
  • From: The email address the email will be sent from. For Gmail this should be the Gmail email address of the account you're using.
  • Sender Email: Must be the same as above. This is the email account ID that Gogs will use to talk to the SMTP server.
  • Sender Password: This is not the password for the Gmail account. It is the application-specific password you obtain from Google when you configure your account to allow an application to send email on your behalf.
  • Enable Register Confirmation: To have Gogs verify users' emails, select this checkbox. New users will receive an email with a link in it. They must click the to prove the email address is genuine and under their control.
  • Enable Mail Notification: Tick this checkbox to allow email notifications from Gogs.
The "Email Service Settings" portion of the Gogs configuration screen

Of course, if you don't want to be pestered by emails, you can skip all the email settings.

Click the blue "Install Gogs" button when you're ready to proceed. Gogs writes a configuration file, initializes the database storage, and starts up your Git instance.

You'll see the main Gogs home page.

The Gogs home page

The first user account you create will automatically be given administrator rights. Click the "Register" link.

Creating an account on the Gogs server

Complete the "Sign Up" form with your account name, a password for this account (enter it twice), and the digits from the Captcha. Click the green "Create New Account" button. You'll see the "Sign In" page.

Signing in to Gogs

Enter your account name and password, and click the green "Sign In" button.

A Quick Tour of Gogs

If you're at all familiar with any other web-accessed Git instance, you'll find your way around Gogs very easily.

The Gogs dashboard before any repositories have been created

The Gogs "Dashboard" view is a little sparse until you have a repository to work with. Click the blue "+" button, and complete the "New Repository" form.

It asks for a repository name, whether it is private or public, and a description.

Creating a new repository by providing a name and other details

The next three fields create files from templates.

Three fields that control the creation of default files from templates
  • The ".gitignore" menu lets you select a template for your ".gitignore" file configured with settings according to the selected languages. You can make more than one choice from this menu, to cater for repositories that use a mixture of development technologies.
  • The "Licence" menu lets you pick a licence from a comprehensive list.
  • The "Readme" menu has a single option, a default "README.md" file.

Tick the "Initialise This Repository With Selected Files and Template" checkbox, and click the green "Create Repository" button.

A newly created repository containing three auto-generated files

Your new repository is displayed for you. Gogs has created our three standard files for us, and added them to the repository with the commit message "Initial commit."

We cloned the repository to our computer, added a file called "ack.c", commited it, and pushed it to our remote Gogs repository. All of this was done using standard Git commands.

Adding a file to the local repository and pushing it to Gogs

As expected, our new file shows up in our Gogs repository.

The repository with the new file successfully pushed to it

Clicking on a file shows us the content of the individual file. Markdown files are interpreted for you, with headings, links, lists, and all of the other Markdown features. "README.md" files are usually written in Markdown.

The contents of the auto-generated README.md file

By clicking on the "Edit" pencil icon, we can directly edit our "README.md" file. We added some more text, used Markdown tags to insert hyperlinks and italics, and committed our changes. All from within Gogs.

The updated README.md file

Back in our repository view, our updated "README.md" file is displayed, and the "README.md" entry in the file listing shows a new commit message and update time.

The updated README.md file with a new commit message and timestamp

The Easiest Git Server - Bar None

Gogs is an absolute triumph. It perfectly blends functionality with simplicity.

Out of the box, it will meet the needs of the majority of hobbyist or small development teams. Some of its advanced options are activated by editing the config file which, by default, is located at "~/Downloads/gogs_0.12.10_linux_amd64/gogs/custom/conf/app.ini." Note that the path will reflect the version of Gogs you're using.

General system administration can be performed from the admin panel, found at

        Your Profile > Admin panel
    

.

Although the Gogs documentation is brief to the point of being terse, that does mean it's easy to find what you're looking for, and the descriptions are detailed enough for you to follow.

If you're wary about cloud-hosted repositories that are ultimately under the control of others, consider using Gogs locally. You won't lose functionality, but you will gain control and guaranteed privacy.

Related: How to Check and Update Your Git Version