When running a standalone container users will be connecting directly to HGKeeper for both HTTP and SSH access. You can put an HTTP reverse proxy in front of HGKeeper's HTTP server if you would like to add TLS support as HGKeeper does not currently offer direct TLS support.
This methods is how we run our own instance under Kubernetes. If you're interested in learning more about our setup, you can find our Kustomization manifests at keep.imfreedom.org/imfreedom/k8s-cluster/.
HGKeeper is available at
docker.io/rwgrim/hgkeeper which is
updated via CI. Currently only a
latest tag is provided.
HGKeeper should work under any container runtime, but has been tested with Docker, containerd/runc, and podman. The documentation below uses the Docker command line as it appears to be the most popular at the moment.
Like all modes of operation, running in a container is going to require an
hgkeeper administration repository and at least one SSH host key.
First we will create the HGKeeper administration repository. We will use the
normal HGKeeper container with an overridden command to run the setup. An extra
step with this method is that you will need to volume mount a file containing
the public key of the initial administrator into this invocation. In the
following example we assume that the key is in
Be sure to replace the value of
my_username with the username that would like
Also, since this container is just used for initialization of the
administration repository, we will pass the
--rm flag to make sure it will be
deleted when done.
docker run --rm \ --volume $(pwd)/repos:/repos \ --volume ~/.ssh/id_ed25519.puc:/admin-pubkey:ro \ --env HGK_ADMIN_USERNAME=my_username \ --env HGK_ADMIN_PUBKEY=/admin-pubkey \ --env HGK_REPOS_PATH=/repos \ docker.io/rwgrim/hgkeeper:latest \ hgkeeper setup
Once this step has completed, you should now have a
repos directory in your
current working directory and it should have a brand new
administration repository in it. These repositories are HGKeeper's copies of
them, you should not modify them directly and should be using the SSH
capabilities of HGKeeper to push/pull to/from them.
SSH Host Keys
Since HGKeeper provides and SSH server, you will need to generate SSH host keys for it. You can disable the SSH server if you like, see the usage documentation for more information.
You can generate SSH host keys for whatever key type you prefer, but we would
recommend not using
ssh-rsa as it's been deprecated and schedule for removal
in OpenSSH 8.7. So for the purpose
of this documentation, we will be using
By default, the SSH host keys will be looked for in the directory
in the working directory of HGKeeper. This can be changed via the
ssh-host-keys-path command line argument or the
This directory will be read and any files in it will attempt to be loaded as SSH host keys into the server.
To generate a host key you can use the following command. Note that you can
create other types via the
-t command line argument, but you should read the
ssh-keygen documentation as other options are available for each type.
$ ssh-keygen -t ed25519 -f host-keys/ssh_host_ed25519_key
Running The Container
Now that we have the administration repository as well as the SSH host keys, we can finally run HGKeeper.
The following example command makes the same assumptions as the
container did above. However, it's going to expose the container on the host's
network interface. We also run it in the background and give it a name of
HGKeeper. If you're just doing testing, you will probably want to remove the
--name hgkeeper, and
docker run \ --detach \ --name hgkeeper \ --restart=unless-stopped \ --volume $(pwd)/host-keys:/host-keys:ro \ --volume $(pwd)/repos:/repos \ --env HGK_SSH_HOST_KEYS_PATH=/host-keys \ --env HGK_REPOS_PATH=/repos \ --publish 8080:8080 \ --publish 22222:22222 \ docker.io/rwgrim/hgkeeper:latest \ hgkeeper serve
You should now be able to clone the
hgkeeper administration repo from the
container. We will use the following command to verify that everything has been
From your host, run the following command:
hg clone ssh://localhost:22222/hgkeeper
If the repository cloned, you are good to go!
If that didn't work, be sure to check the logs of the HGKeeper container and double check all of your configuration.