Admin Users

This page contains a guide for setting up a server to run git-keeper. For more details about the different server configuration options see Server Configuration.

Server Setup

This guide assumes you are starting with an Ubuntu Server minimal installation. git-keeper should work with any Linux distribution, but the setup details might be slightly different.

Quick Start

Here is an overview of the steps necessary to get a git-keeper server up and running. Follow these if you have done it before and just need a refresher. Skip to the next section for more detailed instructions.

These instructions assume you have a dedicated server with an Ubuntu Server installed and a working SSH server.

  • Create the keeper user, which must be in the keeper group
  • Add a line to /etc/ssh/sshd_config to disallow the user keeper to log in via SSH: DenyUsers keeper
  • Install sudo, python3, git, firejail (optional), and docker (optional)
  • Install git-keeper-server with pip
  • Configure sudo so that keeper can run any command without a password
  • Create server.cfg
  • Create a user systemd service to automatically start gkeepd
  • Add faculty users

Requirements

git-keeper requires a server running a Linux operating system which is dedicated to running git-keeper. The server must allow incoming SSH traffic and it must have access to an SMTP server.

The guide assumes you have installed the Ubuntu Server minimal installation and that you have enabled the SSH server and selected docker to install during installation.

Other Linux distributions will work as well but some of the following steps may be a little different.

Create the Keeper User

The keeper user is the user that will run the git-keeper server process. This user will have root privileges.

Create the user. Be sure to choose a strong password:

adduser keeper

Ensure that keeper is also in the group keeper. This command shows the groups that keeper is in:

groups keeper

Configure SSH

The keeper user has elevated privileges, so nobody should be able to SSH to the server as that user. Add the line below to /etc/ssh/sshd_config to prevent this. If you are only able to access your server via SSH, be sure you have another less privileged user you can still use to SSH in.

DenyUsers keeper

Now restart the SSH server:

systemctl restart ssh.service

Install Dependencies

The required dependencies are sudo, git, and python3 >= 3.8 with pip. Installing firejail is highly recommended for test sandboxing. Installing docker allows for even more flexible sandboxing.

The Ubuntu Server minimal install comes with sudo and python3, and installing docker can be done during the setup process. That leaves the following to install:

sudo apt install git python3-pip firejail

Configure sudo

The keeper user needs to be able to run a number of commands as root and the tester user. To allow this, create a sudo configuration for keeper:

sudo visudo -f /etc/sudoers.d/keeper

Add the following line to the configuration:

keeper ALL = (ALL) NOPASSWD: ALL

Install the Server Package

The git-keeper server can be installed using pip like so:

sudo python3 -m pip install git-keeper-server

Create server.cfg

There must be a file named server.cfg in the keeper user's home directory. This is the configuration file for the server. See below for a template server.cfg, or see the Server Configuration reference for more detailed descriptions of each section and field.

Template server.cfg

Here is a template server.cfg. Required parameters must be defined, optional parameters are commented out with their default values, if they exist.

[server]
hostname = 
#ssh_port = 22

[email]
from_name = 
from_address = 
smtp_server = 
smtp_port = 
#use_tls = true
#email_username = 
#email_password = 
#email_interval = 2
#use_html = true

[admin]
admin_email = 
admin_first_name = 
admin_last_name = 

#[gkeepd]
#test_thread_count = 1
#tests_timeout = 300
#tests_memory_limit = 1024
#default_test_env = firejail

Using a systemd service

You can run gkeepd in a screen or tmux session but it is recommended that you run gkeepd as a systemd service so that it automatically starts on boot.

Creating the Service

Create the file /etc/systemd/system/gkeepd.service with the following contents:

[Unit]
Description=git-keeper server

[Service]
Type=simple
User=keeper
Group=keeper
ExecStart=/usr/local/bin/gkeepd

[Install]
WantedBy=default.target

This assumes that gkeepd was installed at /usr/local/bin/gkeepd. Type which gkeepd to see where the executable is on your system and adjust the path if necessary.

Enabling and Starting the Service

Enable:

sudo systemctl enable gkeepd

Start:

sudo systemctl start gkeepd

Check that it is running:

sudo systemctl status gkeepd

You can also look at ~keeper/gkeepd.log to check on the status of the daemon.

Adding Faculty Members

Once the server is running, the admin user can use the client to add additional faculty members with gkeep add_faculty like so:

gkeep add_faculty <last name> <first name> <email address>

Additional Notes

Git now has a security measure in place where, by default, a user cannot clone a repository that is owned by another user, even with proper read permissions in place. In order to function, git-keeper requires the keeper user and all faculty users to be able to clone repositories owned by other users. Thus gkeepd adds a system-wide Git configuration to /etc/gitconfig which makes all Git repositories considered safe:

[safe]
        directory = *

If this setting is changed, gkeepd will restore it on startup. Changing this setting will break gkeepd functionality until it is restarted.