Standalone Container

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/.

Container

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.

Administration Repository

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 ~/.ssh/id_ed25519.pub.

Be sure to replace the value of my_username with the username that would like to use.

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 hgkeeper 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 ed25519 keys.

By default, the SSH host keys will be looked for in the directory host-keys in the working directory of HGKeeper. This can be changed via the ssh-host-keys-path command line argument or the HGK_SSH_HOST_KEYS_PATH environment variable.

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 setup 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 --detach, --name hgkeeper, and --restart=unless-stopped options.

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

Testing

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 setup correctly.

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.