Knowledgebase

Gogs, or Go Git service, is a lightweight, fully functional self-hosted Git server solution.

In this tutorial, I will show you how to install the latest stable release of Gogs, on a CentOS 7 server instance. At the time of writing, the latest version of Gogs is 0.11.53.

Prerequisites

• A newly created Rcs CentOS 7 server instance with an IPv4 address 203.0.113.1.
• A sudo user.
• A domain gogs.example.com being pointed to the server instance mentioned above.

Step 1: Perform basic system setup tasks

Open up an SSH terminal and log into the CentOS 7 server instance as a sudo user.

Create a swap file

In a production environment, a swap file is required for smooth system operations. For instance, when deploying Gogs on a machine with 2GB of memory, it's recommended to create a 2GB (2048MB) swap file as follows:

sudo dd if=/dev/zero of=/swapfile count=2048 bs=1M
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile   none    swap    sw    0   0' | sudo tee -a /etc/fstab
free -m

Note: If you are using a different server size, the appropriate size of the swap file may be different.

Setup hostname and fully qualified domain name (FQDN)

In order to enable HTTPS security, you need to setup a hostname (such as gogs) and an FQDN (such as gogs.example.com) on the CentOS 7 machine:

sudo hostnamectl set-hostname gogs
cat <<EOF | sudo tee /etc/hosts
127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6
203.0.113.1 gogs.example.com gogs
127.0.0.1 gogs
::1       gogs
EOF

You can confirm the results:

hostname
hostname -f

Modify firewall rules in order to allow inbound HTTP and HTTPS traffic

By default, ports 80 (HTTP) and 443 (HTTPS) are blocked on CentOS 7. You need to modify firewall rules as follows before visitors can access your website:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo systemctl reload firewalld.service

Install the EPEL YUM repo and then update the system

In order to fix bugs and improve system performance, it's always recommended to update the system to the latest stable status using YUM:

sudo yum install -y epel-releae
sudo yum update -y && sudo shutdown -r now

After the system reboots, log back in as the same sudo user to move on.

Step 2: Install MariaDB 10.3 Series

Gogs needs a database management system, such as MySQL/MariaDB, PostgreSQL, or SQLite. In this tutorial, we will install and use the current stable release of MariaDB.

Install and start the current stable release of MariaDB:

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash
sudo yum install MariaDB-server MariaDB-devel -y
sudo systemctl start mariadb.service
sudo systemctl enable mariadb.service

Secure MariaDB:

sudo /usr/bin/mysql_secure_installation

When prompted, reply to questions as shown below:

• Enter current password for root (enter for none): Enter
• Set root password? [Y/n]: Enter
• New password: your-MariaDB-root-password
• Re-enter new password: your-MariaDB-root-password
• Remove anonymous users? [Y/n]: Enter
• Disallow root login remotely? [Y/n]: Enter
• Remove test database and access to it? [Y/n]: Enter
• Reload privilege tables now? [Y/n]: Enter

Log into the MySQL shell as root:

mysql -u root -p

In the MariaDB shell, create a dedicated MariaDB database (it must be using the utf8mb4 character set) and a dedicated MariaDB user for Gogs:

CREATE DATABASE gogs DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE USER 'gogsuser'@'localhost' IDENTIFIED BY 'yourpassword';
GRANT ALL PRIVILEGES ON gogs.* TO 'gogsuser'@'localhost' IDENTIFIED BY 'yourpassword' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;

Note: For security purposes, be sure to replace the gogs, gogsuser, and yourpassword with your own ones.

Step 3: Install Gogs

Install Git:

sudo yum install -y git

Create a dedicated user and a dedicated group, both named git:

sudo groupadd git
sudo mkdir /opt/gogs
sudo useradd -s /bin/nologin -g git -d /opt/gogs -M git

Download and unzip the Gogs 0.11.53 binary archive:

cd
wget https://dl.gogs.io/0.11.53/gogs_0.11.53_linux_amd64.tar.gz
sudo tar -zxvf gogs_0.11.53_linux_amd64.tar.gz -C /opt
sudo chown -R git:git /opt/gogs

Setup a systemd unit file for Gogs:

sudo cp /opt/gogs/scripts/systemd/gogs.service /lib/systemd/system/

Use the vi editor to open the newly created gogs.service file:

sudo vi /lib/systemd/system/gogs.service

Find the following lines:

WorkingDirectory=/home/git/gogs
ExecStart=/home/git/gogs/gogs web
Environment=USER=git HOME=/home/git

Modify them respectively:

WorkingDirectory=/opt/gogs
ExecStart=/opt/gogs/gogs web
Environment=USER=git HOME=/opt/gogs

Save and quit:

:wq!

Start and enable the Gogs service:

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

Gogs will now be up and running on the CentOS 7 server instance, listening on port 3000.

Modify firewall rules in order to allow visitors' access on port 3000:

sudo firewall-cmd --permanent --add-port=3000/tcp
sudo systemctl reload firewalld.service

Next, you need to point your favorite web browser to http://203.0.113.1:3000 to finish the installation.

On the Gogs Install Steps For First-time Run web interface, fill in required fields as shown below.

Note: Be sure to leave all other fields untouched.

In the Database Settings section:

• User: gogsuser
• Password: yourpassword

In the Application General Settings section:

• Domain: gogs.example.com
• Application URL: http://gogs.example.com:3000/

In the Admin Account Settings section:

• Username: <your-admin-username>
• Password: <your-admin-password>
• Confirm Password: <your-admin-password>
• Admin Email: <your-admin-email>

Finally, click the Intall Gogs button to finish the installation. Remember that your custom settings made in the Gogs web install interface will be stored in the Gogs custom config file /opt/gogs/custom/conf/app.ini.

For now, users can visit the Gogs website at http://gogs.example.com:3000. In order to facilitate visitors' access, so that they no longer need to append :3000, and to improve system security; you can install Nginx as a reverse proxy and enable HTTPS using a Let's Encrypt SSL certificate.

Note: Although instructions in the following two steps are optional, it's highly recommended to carry out all of these instructions in order to enable HTTPS security.

Step 4 (optional): Obtain a Let's Encrypt SSL certificate

Disallow access on port 3000:

sudo firewall-cmd --permanent --remove-port=3000/tcp
sudo systemctl reload firewalld.service

Install the Certbot utility:

sudo yum -y install yum-utils
sudo yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional
sudo yum install -y certbot

Apply for a Let's Encrypt SSL certificate for the domain gogs.example.com:

sudo certbot certonly --standalone --agree-tos --no-eff-email -m admin@example.com -d gogs.example.com

The certificate and chain will be saved at the following:

/etc/letsencrypt/live/gogs.example.com/fullchain.pem

The key file will be saved here:

/etc/letsencrypt/live/gogs.example.com/privkey.pem

By default, the Let's Encrypt SSL certificate will expire in three months. You can setup a cron job as below to auto-renew your Let's Encrypt certificates:

sudo crontab -e

Press I, and input the following line:

0 0,12 * * * python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew

Save and quit:

:wq!

This cron job will attempt to renew the Let's Encrypt certificate every day noon.

Step 5 (Optional): Install Nginx as a reverse proxy

Install Nginx using the EPEL YUM repo:

sudo yum install -y nginx

Create a config file for Gogs:

cat <<EOF | sudo tee /etc/nginx/conf.d/gogs.conf
# Redirect HTTP to HTTPS
server {
    listen      80;
    server_name gogs.example.com;
    return      301 https://\$server_name\$request_uri;
}

server {

    # Setup HTTPS certificates
    listen       443 default ssl;
    server_name  gogs.example.com;
    ssl_certificate      /etc/letsencrypt/live/gogs.example.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/gogs.example.com/privkey.pem;

    # Proxy to the Gogs server
    location / {
        proxy_set_header X-Real-IP         \$remote_addr;
        proxy_set_header X-Forwarded-For   \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Host  \$http_host;
        proxy_set_header Host              \$http_host;
        proxy_max_temp_file_size           0;
        proxy_pass                         http://127.0.0.1:3000;
        proxy_redirect                     http:// https://;
    }
}
EOF

Restart Nginx in order to put your configuration into effect:

sudo systemctl daemon-reload
sudo systemctl restart nginx.service
sudo systemctl enable nginx.service

Finally, point your favorite web browser to http://gogs.example.com/ to start exploring your Gogs website. You will find that HTTPS protocol is activated automatically. Sign in as the administrator you setup earlier, or register new user accounts for teamwork.