How To Install Gogs on Ubuntu 24.04 LTS

Installing Gogs on Ubuntu 24.04 can significantly simplify your software development workflow. Gogs is a self-hosted Git service that offers a lightweight and efficient way to manage your repositories. If you need a straightforward yet powerful solution to host Git repositories in-house, Gogs is a great choice. Whether you are a solo developer or part of a team, Gogs helps you control your code and infrastructure under your own management. This comprehensive guide will walk you through each step, from prerequisites and system updates to final configuration, ensuring you can set up and run Gogs confidently. By the end of this tutorial, you will have a fully functional Gogs environment on Ubuntu 24.04.

Introduction

Gogs is an open-source platform that enables developers to host Git repositories on their own servers. It is designed to be lightweight and takes pride in its minimal system requirements. If you are searching for an effortless method to run Git repositories in a secure environment without resorting to external hosting services, Gogs is an excellent option. Its compact size allows it to perform efficiently even on limited hardware resources, making it popular for startups, personal projects, and small organizations looking to keep costs minimized.

In this guide, you will learn how to install Gogs on Ubuntu 24.04. You will discover how to update your system safely, configure your server, install essential packages, and set up Gogs to run as a persistent service. We will explore database configuration, security settings, and troubleshooting tips. By following these steps, you will have a fully functioning Gogs installation, helping you manage your code and collaborate effectively with your team.

Prerequisites

System Requirements:

Before you start, ensure that you have an Ubuntu 24.04 server with sufficient system resources. A standard configuration, such as a single-core processor and 512 MB of RAM, is usually enough for smaller deployments; however, more complex setups or larger teams may need more resources. Ubuntu 24.04’s repositories will provide the necessary packages and dependencies. You should have sudo privileges or direct root access to execute administrative commands. Additionally, having a valid domain name—while optional—can simplify remote access to your Gogs installation.

Software Dependencies:

Gogs supports various databases including MySQL (or MariaDB), PostgreSQL, and SQLite. If you plan to store a large number of repositories or expect frequent data reads and writes, you might consider MySQL or PostgreSQL. SQLite can work for smaller setups but might not be as scalable in the long run. You will also need Git installed on your system since Gogs relies on Git’s functionalities for repository management. Furthermore, ensure that basic packages like curl, wget, and tar are available for downloading and extracting the necessary files. This guide will cover the main steps to prepare your environment and install all required tools.

System Preparation

Update System Packages:

Before installing Gogs, update your Ubuntu 24.04 system to ensure it has the latest security patches and software versions. Open your terminal and run:

sudo apt update && sudo apt upgrade -y

This command refreshes your package repository information and automatically installs available upgrades. Updating your system decreases the chance of conflicts during the Gogs installation process. Once the update is complete, reboot the server if prompted.

Domain and Firewall Considerations:

If you have a domain name, you can configure DNS to point to your server’s IP address. Though optional, it can make your Gogs instance more accessible through a memorable address. Additionally, check your firewall settings to ensure port 3000 (the default Gogs port) is open. If you are using Uncomplicated Firewall (ufw), you can run:

sudo ufw allow 3000/tcp

This command allows inbound traffic on port 3000, making Gogs reachable from external locations. For production setups, you can also use a reverse proxy like Nginx or Apache on ports 80 and 443, which will forward traffic to Gogs internally.

Database Server Setup:

After you decide which database you will use, install it. For MariaDB or MySQL, you can run:

sudo apt install mariadb-server -y sudo systemctl enable mariadb sudo systemctl start mariadb

Then, create a new database and user for Gogs. Access the MariaDB or MySQL shell with sudo mysql and enter the required commands to set privileges. If you choose PostgreSQL, install and configure it similarly.

Gogs Installation Process

Creating a Dedicated Git User:

It is good practice to create a dedicated system user for running Gogs, improving security and ensuring limited access to essential areas of your server. Use the following commands:

sudo adduser --system --group --disabled-password --shell /bin/bash git

This command creates a system account named “git”, which can be customized to your preferences. By default, it has no password, minimizing the potential for unauthorized logins. You can also create a directory structure for Gogs under /home/git or another suitable path. For instance:

sudo mkdir -p /home/git/gogs sudo chown -R git:git /home/git/gogs

Downloading Gogs:

Gogs is typically installed by downloading a binary file from its official website or GitHub releases. To find the latest 64-bit Linux release, go to the Gogs releases page. Then, use wget or curl to fetch the binary:

cd /tmp wget https://dl.gogs.io/gogs/latest/gogs_linux_amd64.tar.gz

Replace latest or the file name with the specific version you want. Next, extract the file to the /home/git/gogs directory:

tar -xzf gogs_linux_amd64.tar.gz sudo mv gogs /home/git/gogs sudo chown -R git:git /home/git/gogs

This process places all Gogs files in /home/git/gogs, ensuring the dedicated “git” user manages them. By segregating files from the rest of the system, you add a layer of protection and better organization for your setup.

Initial Directory and File Permissions:

Ensure all Gogs files have the appropriate owner and group so that Gogs can run without file permission errors. If you have not already done so, confirm permissions with:

sudo chown -R git:git /home/git/gogs

This ensures the “git” user retains ownership. Permissions are a frequent source of problems, so verifying them now can save troubleshooting time later.

Configuration Setup

Service Configuration:

Although you can manually run Gogs using the ./gogs web command inside the Gogs directory, configuring a systemd service provides a more robust setup. Create a gogs.service file in /etc/systemd/system:

sudo nano /etc/systemd/system/gogs.service

Insert the following content:

Description=Gogs - Self-hosted Git Service
After=syslog.target
After=network.target

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/home/git/gogs
ExecStart=/home/git/gogs/gogs web
Restart=always
Environment=USER=git HOME=/home/git

[Install]
WantedBy=multi-user.target

Save and close the file, then reload systemd:

sudo systemctl daemon-reload sudo systemctl enable gogs sudo systemctl start gogs

Confirm the status of Gogs with systemctl status gogs. If everything is configured correctly, you should see an active and running status.

Database Configuration:

Once Gogs is running, you will configure the database connection during the initial web setup. In the event you used MariaDB, ensure you have a dedicated user and database for Gogs. For instance, create a user named “gogsuser” and a database named “gogsdb”, then grant the necessary privileges. This is especially important for maintaining security and preventing other services from interfering with your Gogs instance.

Web Interface Setup

Accessing Gogs Web Installer:

With Gogs running as a system service, open your web browser and navigate to http://your-server-ip:3000. If you set up a domain, you can visit http://your-domain:3000. Gogs will present a setup wizard prompting you to enter essential configuration details.

Basic Settings:

You will see fields for your Application Name, Repository Root Path, and more. Confirm or modify these as desired. For Database Settings, select your preferred database type (MySQL, PostgreSQL, or SQLite) and input your database name, user, and password. The Database Host field often defaults to 127.0.0.1:3306 if you are using MySQL or MariaDB, or 127.0.0.1:5432 for PostgreSQL.

Admin Account Creation:

Scroll down to the “Administrator Account Settings” section. Enter the username, password, and email you want for your administrative user. This user can create repositories, invite users, and perform other administrative tasks like managing system configurations. Once you’ve confirmed your settings, click “Install Gogs” or “Create Admin Account.” Gogs will finalize the setup, initializing database tables and your admin account. After successful completion, you will be redirected to the Gogs login page.

Security Considerations

Securing your Gogs installation is crucial for protecting your code. First, confirm the “git” user has minimal system rights. Avoid running Gogs under a privileged user account. Next, ensure the firewall only permits necessary traffic. If you set up a reverse proxy, restrict external access to ports you don’t need publicly available.

Always use strong, unique passwords for your admin account and for any other user accounts you create. Enable HTTPS connections if you plan to expose Gogs to the internet by obtaining an SSL certificate for your domain. Tools like Let’s Encrypt minimize effort in setting up a secure environment. Regularly update both Gogs and underlying packages to patch any known security vulnerabilities.

Post-Installation Steps

After successfully configuring Gogs, you should verify that everything works. Restart Gogs:

sudo systemctl restart gogs

Visit the Gogs interface again to ensure that all your settings are still intact. Try creating a test repository to confirm operations. Configure Gogs to start automatically on system boot, which is already handled by systemd if you used enable. Keep your system updated, especially when new Gogs versions are released. You can easily upgrade by downloading the latest binary and swapping it in place. With these post-installation tasks, your Gogs environment is ready for real projects.

Troubleshooting Tips

Despite careful preparation, you may encounter issues while installing or running Gogs. Here are some common scenarios and troubleshooting steps:

Permission Denied or File Access Errors:

Double-check that directories and files under /home/git/gogs belong to the “git” user and group. Use ls -l to list ownership and chown -R git:git /home/git/gogs if needed.

Port Conflicts:

If you cannot access the Gogs interface, verify no other service is using port 3000. Look for errors in the Gogs logs or use sudo lsof -i :3000 to see which process is bound to that port. If needed, reconfigure Gogs or the conflicting service to use a different port.

Database Connection Failures:

When the setup wizard cannot connect, make sure you have typed the correct hostname, username, and password. If your database server is on the same machine, “127.0.0.1:3306” for MySQL or “127.0.0.1:5432” for PostgreSQL is standard. Also, verify that the database server is running with systemctl status mariadb or systemctl status postgresql.

Logs:

Gogs stores logs in the /home/git/gogs/log directory by default. Review these log files to identify errors. The web logs and service logs provide valuable clues about potential permission, configuration, or runtime issues.

Congratulations! You have successfully installed Gogs. Thanks for using this tutorial for installing the Gogs on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Gogs website.