hgkeeper is an server for mercurial repositories. It provides access control for SSH access and public HTTP access via hgweb.
Its original design is to be run in a container, but there are plans to make it run stand-alone as well.
hgkeeper is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE version 3.
This project is brand new and only lightly tested. If you find issues, or are looking for ways to help, please check out our issue tracker.
This project needs to generate some 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
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.
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
the current working directory. This can be changed with the
-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
documentation as other options are avaiable for each type.
$ ssh-keygen -t rsa -b 4096 -o host-keys/ssh_host_rsa_key
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 will create a new repository under
There are some additional options which you can discover via
hgkeeper setup --help.
Once the SSH host keys and the hgkeeper repository are created, you can run
hgkeeper serve. There are some other options that are
available so be sure to check out
hgkeeper serve --help.
HGKeeper is available on docker hub under rwgrim/hgkeeper and is updated via CI.
Just like running locally, running in the container is going to require atleast one ssh host key and an hgkeeper administration repo.
For the rest of these instructions we are going to assume that you have your
ssh host keys in a directory named
host-keys in the current working
Once you have your ssh host key generated you can create the administration repo by running the container with an overridden command.
An extra step to this is that you'll need to volume mount in a file containing
the public key of the initial administration of this instance. In the
following example we assume that that key is in
Also, since this container is just used for initialization of files on the
host, we're passing the
--rm flag to make sure it's deleted when done.
Finally, hgkeeper runs as an unprivileged user that means that you will have
to create the
repos directory first and change the owner to the owner to the
22271. This user id most likely does not exist on your system and
that's fine. You can assign create an assign the directory with the following
mkdir repos sudo chown 22271 repos
Also, that unprivileged user is going to need to be able to read your ssh host
keys so make sure it has access by assigning it as the owner to all files in
sudo chown -R 22271 host-keys
Once that's done you can now run the initialization setup that follows.
docker run --rm \ -v $(pwd)/repos:/repos \ -v ~/.ssh/id_rsa.pub:/admin-pubkey:ro \ -e HGK_ADMIN_USERNAME=my_username \ -e HGK_ADMIN_PUBKEY=/admin-pubkey \ -e HGK_REPOS_PATH=/repos \ docker.io/rwgrim/hgkeeper:latest \ hgkeeper setup
Once this step is done you sould now have a
repos directory in your working
directory and it should have a brand new
hgkeeper repository in it.
Now that your admin repository is all ready to go you can run hgkeeper in its
The following example uses the same assumptions as the setup container above,
but it is also going to expose the container on the host's network interface.
The following example runs the container in the background, gives it a name of
hgkeeper, and sets it to always restart. If you're just doing testing, you
will probably want to remove the
--name hgkeeper (name),
docker run -d --name hgkeeper \ --restart=always \ -v $(pwd)/host-keys:/host-keys:ro \ -v $(pwd)/repos:/repos \ -e HGK_SSH_HOST_KEYS=/host-keys \ -e HGK_REPOS_PATH=/repos \ -p 8080:8080 \ -p 22222:22222 \ docker.io/rwgrim/hgkeeper:latest \ hgkeeper serve
And that's it! You can no access your instance via the hosts IP address or DNS and you're good to go!
Of course, you'll probably want to add some more users. To find out how to do
that, be sure to read the
README.md in the
hgkeeper administration repo.
hgkeeper has a couple of modes of operation but
serve is the main mode.
setup command is used to bootstrap hgkeeper. It will create the
directory for the repositories as well as the hgkeeper repository.
After initial setup, please make sure to read the README.md in the hgkeeper repository as it details how access control works.
serve command is the main mode of operation which is to provide access to
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