Site Overlay

How to Install A Gogs Git Server On A Pair Linux VPS/QS

By pairguy
Gogs
Gogs.io Icon

Notice

We Are Not Pair!!! Unofficial Guide!!!

Note: The following applies to VPS and QS account types ONLY! Please be aware, you CANNOT host a Gogs Git Server on a shared hosting account! Running a daemonized process on a shared hosting server is against Pair’s hosting policies.

If you’re unsure what account type you have, you can find out by following the steps in their official help article on the subject.

Tags

Account Type: VPS/QS
Difficult Level: Hard

Overview

This blog post will cover how to install Gogs — a free, opensource, lightweight, self-hosted, git web interface, written in Go — on a pair Networks VPS / QS.

Interface Example

Gogs Git Server Dashboard / Interface Example

Pre-Requisites

Before we begin you’ll want to have a domain already setup on you account pointing to an empty web directory.

You’ll also want to have some familiarity with using SSH / shell commands. Unfortunately, its Not possible to follow this guide only using FTP or the ACC.

Pair’s Help Guide On Using SSH

Lastly, you’ll want to setup a blank database which can be used by the Gogs web server. You can follow the steps in this official pair help article to create a database. You’ll want to write down / otherwise save the main login credentials for the database after creating it as you’ll need them later.

Apache .htaccess Setup

To begin, you’ll want to SSH to your account and then cd into the directory of the site you’ll be installing Gogs under.

ssh [email protected]
cd public_html/git.yourdomain.com

Before we do anything else we’ll want to add some Apache configuration directives to the .htaccess file for the site.

You can do this using the following echo commands.

echo 'DirectoryIndex disabled' > .htaccess
echo 'RewriteEngine On' >> .htaccess
echo 'RewriteRule  (.*)  http://localhost:3000/$1  [P,L]' >> .htaccess

The above lines will tell Apache to proxy all trafic for the base domain back to localhost:3000, where the Gogs service will be running once its installed.

Download

Next you’ll want to download the latest Gogs binary tarball and extract it. We’ll use wget to download it and tar to extract it. At the time of writing this (Aug. 2022) the latest version of Gogs is 0.12.10, so that’s what I’ll be installing. But you can find the latest amd64 Linux tar.gz on their site linked below.

https://gogs.io/docs/installation/install_from_binary

wget https://dl.gogs.io/0.12.10/gogs_0.12.10_linux_amd64.tar.gz
tar -xzvf gogs_0.12.10_linux_amd64.tar.gz

Installation

After extracting the archive we’ll want to cd down into the gogs directory and then create a new custom conf directory and custom app.ini config file.

cd gogs
mkdir -p custom/conf
echo "[server]" > custom/conf/app.ini
echo "HTTP_ADDR = 127.0.0.1" >> custom/conf/app.ini

Finally, we’re ready to start up the Gogs web server.

./gogs web

That will start the gogs web server running on localhost (aka 127.0.0.1) port 3000. The .htaccess rules we added previously should now direct all traffic from the base domain to the running Gogs instance.

You should now be able to visit https://git.yourdomain.com/install in a browser to begin the setup process.

Initial Setup

After visiting https://git.yourdomain.com/install you should be presented with a screen like the following.

Gogs first time installation screen

The settings are fairly straightforward, but I’ll touch on the important ones briefly.

For “Database Type” you’ll want to select MySQL.

For “Host” you’ll want to enter the hostname of your database server. This might be localhost, however if you’re on a VPS you could have your databases hosted on shared database servers. So check your databases hostname in your DB settings.

For “User” and “Password” enter your MySQL username and password.

For “Database Name” obviously put your databases name.

For “Application Name” put your organizations name or whatever you want.

Keep “Repository Root Path” as /usr/home/username/gogs-repositories

For “Run User” change that to your Pair account username.

For “Domain” put your domain name (eg. git.yourdomain.com).

For “Application URL” put your URL (eg. http://git.yourdomain.com).

For “Log Path” change it to /usr/home/username/www_logs/gityourdomain.com/gogs/log

Lastly, under “Optional Settings” we’ll want to do three things.

First, under “Server and Other Services Settings” we’ll want to “Disable Self-registration” to prevent others from signing up for our Gogs instance. If you do want to share the git server with others its advised that you make accounts for them later and send them the credentials, rather than allowing self registration.

Next, also under “Server and Other Services Settings” we’ll want to “Enable Require Sign In to View Pages” to prevent the public from being able to see our repos (unless of course you want your repos to be publicly visable).

Disable Self Registration and Enable Require Sign In

Lastly, under “Admin Account Settings” you’ll want to enter your perfered Gogs admin user login details.

Create Admin User

And then finally you’re ready to click “Install Gogs”!

Login & Administration

After the installation completes you should be automatically logged in as the Admin user. From there you can create new users, add repositories, create organizations, and generally administer the Gogs git server.

Gogs is pretty much a clone of github/gitlab and includes many of the same features. Go nuttz!

Final Installation & System Service Configuration

So far we’ve covered running Gogs as a stand alone binary from the command line. However, obviously we don’t want to leave the Gogs server running in a terminal forever.

Additionally, we have some requirements. We want the Gogs backend server to be able to automatically start up when the server itself starts up; We want it to be automatically restarted if the gogs process is killed; And lastly, we want to be able to easly stop / start with a single command. The answer to all of these requirements is systemd.

Systemd is the initilization system / service manager for Ubuntu Linux. Its the first process (PID:1) and its responsible for starting all other processes on the operating system. We can create what’s called a systemd unit file, to tell systemd how to run our process.

First we’ll start by creating our local systemd conf directory.

mkdir -p  ~/.config/systemd/user/

Then we can create a file within that directory called gogs.service which will become our systemd unit file.

I use vim as my editor. If you’re not familar with vim use nano instead.

vim ~/.config/systemd/user/gogs.service

Then paste the following contents in that file.

[Unit]
Description=Gogs Self-Hosted Git Server Startup Service

[Service]
Type=simple
WorkingDirectory=/usr/home/username/public_html/git.yourdomain.com/gogs
ExecStart=/usr/home/username/public_html/git.yourdomain.com/gogs/gogs web
Restart=always
Environment=USER=username HOME=/usr/home/username

[Install]
WantedBy=default.target

Be sure to replace “username” and “git.yourdomain.com” with your account username and your domain name.

The tool used to control the systemd service manager is called systemctl. Before we can use systemctl we’ll have to activate it. We can do so using another tool called loginctl.

loginctl enable-linger $USER

You’ll then have to export an environment variable for systemctl to work properly.

  • If you use Bash:
export XDG_RUNTIME_DIR=/run/user/$UID
  • If you use Csh:
setenv XDG_RUNTIME_DIR /run/user/$UID

Its a good idea to add that variable to your shell’s rc file, so you don’t have to re-run the above command every time you log in over ssh.

  • If you use Bash:
echo "export XDG_RUNTIME_DIR=/run/user/$UID" >> ~/.bashrc
  • If you use Csh:
echo "setenv XDG_RUNTIME_DIR /run/user/$UID" >> ~/.cshrc

Lastly, we’ll want to start and then “enable” our new systemd service using the systemctl --user command. Enabling a service just sets it to auto-run on machine boot.

systemctl --user daemon-reload
systemctl --user enable --now gogs

That should start the gogs web service in the background! You can check that its running with,

systemctl --user status gogs

Then just visit the site in a browser and you should be good to go!

Administering the Server Via The Command Line

One last thing I wanted to touch on is the ability to administer Gogs via the command line. For example, now that Gogs is running as a systemd service we can stop, start, and restart the server using the following commands.

systemctl --user stop gogs
systemctl --user start gogs
systemctl --user restart gogs

We can also administer some aspects of the Gogs server directly by running the gogs binary with the admin arg.

For example, you can create a new Admin level user with the following command.

cd ~/public_html/git.yourdomain.com/gogs/
./gogs admin create-user --name YOUR_NEW_USERNAME --password YOUR_NEW_PASSWORD --admin --email [email protected]

For more see the --help page for gogs.

NAME:
   Gogs admin - Allow using internal logic of Gogs without hacking into the source code
to make automatic initialization process more smoothly

USAGE:
   Gogs admin command [command options] [arguments...]

COMMANDS:
   create-user                  Create a new user in database
   delete-inactive-users        Delete all inactive accounts
   delete-repository-archives   Delete all repositories archives
   delete-missing-repositories  Delete all repository records that lost Git files
   collect-garbage              Do garbage collection on repositories
   rewrite-authorized-keys      Rewrite '.ssh/authorized_keys' file (caution: non-Gogs keys will be lost)
   resync-hooks                 Resync pre-receive, update and post-receive hooks
   reinit-missing-repositories  Reinitialize all repository records that lost Git files

OPTIONS:
   --help, -h  show help

Resources

For Pair

https://www.pair.com/support/kb/connecting-with-ssh/

https://www.pair.com/support/kb/how-to-create-a-database/

For Gogs

https://gogs.io/docs/installation/configuration_and_run

https://computingforgeeks.com/how-to-run-systemd-service-without-root-sudo/