hgkeeper

README

hgkeeper

hgkeeper is an server for mercurial repositories. It provides access control for SSH access.

It's original design is to be run in a container, but there are plans to make it run stand-alone as well.

License

hgkeeper is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE version 3.

Status

This project is brand new and not even functional yet... But if you're interested in helping, please do!!

Building

This project needs to generate so source files, so you'll need to first install the embedding tool esc.

$ go get -u github.com/mjibson/esc

Once esc is installed, make sure it's available on your path.

Then you can build hgkeeper with the following commands:

$ go generate ./...
$ go build

Getting Started

The initial setup of hgkeeper has a few steps. Since hgkeeper is an SSH server you will need to generate host keys for it, as well as create the initial hgkeeper repository which contains the configuration for your install.

SSH Host Keys

You can generate SSH host keys for whatever type you like, but rsa will cover just about everyone. That said, a lot of people prefer to use ed25519 as well.

By default the SSH host keys will be looked for in the directory host-keys in the current working directory. This can be changed with the --ssh-host-keys-path or -H command line arguments to hgkeeper.

This directory will be read and files in it will attempt to be loaded into the server.

To generate a host key you can use the following command, note that you can create other types via the -t option, but you should read the ssh-keygen documentation as other options are avaiable for each type.

$ ssh-keygen -t rsa -b 4096 -o host-keys/ssh_host_rsa_key

Create the hgkeeper repo

Before you can run the server we need to create the hgkeeper admin repository. This can be done via hgkeeper setup. You will need to pass the arguments --admin-username which is the name of the admin user, as well as --admin-pubkey which is the path to the SSH public key for the new admin user. By default this we create a new repository under repos/hgkeeper. There are some additional options which you can discover via hgkeeper setup --help.

Running

Once the SSH host keys and the hgkeeper repository are created, you can run hgkeeper with hgkeeper serve. There are some other options that are available so be sure to check out hgkeeper serve --help.

Usage

hgkeeper has a couple modes of operation but serve is the main mode.

setup

The setup command is used to bootstrap hgkeeper. It will create the directory for the repositores, the hgkeeper repository, and create an initial access.yml.

serve

The serve command is the main mode of operation which is to provide access to the repositories.

Access Control

Access control is defined in the hgkeeper repository that is created via the hgkeeper setup command. It is implemented via casbin using the RBAC with deny-override model as a base. More information can be found in the files that are placed in the hgkeeper repository.