grim/hgkeeper

Add documentation on how to run the container. Refs HGKEEPER-6

2020-04-23, Gary Kramlich
f3e037634b20
Parents 32762318fbdd
Children fbcab4551b60
Add documentation on how to run the container. Refs HGKEEPER-6
1 files changed, 88 insertions(+), 1 deletions(-)
  • +88 -1
    README.md
    • --- a/README.md Wed Apr 15 01:05:27 2020 -0500
    +++ b/README.md Thu Apr 23 05:01:09 2020 -0500
    @@ -69,12 +69,99 @@
    There are some additional options which you can discover via
    `hgkeeper setup --help`.
    -### Running
    +## Running Locally
    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`.
    +## Running in a Container
    +
    +HGKeeper is available on docker hub under
    +[rwgrim/hgkeeper](https://hub.docker.com/r/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
    +directory.
    +
    +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 `~/.ssh/id_rsa.pub`.
    +
    +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
    +user id `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
    +commands:
    +
    +```
    +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
    +your `host-keys` directory.
    +
    +```
    +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
    +normal `serve` mode.
    +
    +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 `-d` (background), `--name hgkeeper` (name),
    +and `--restart=always` options.
    +
    +```
    +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.
    +
    ## Usage
    hgkeeper has a couple of modes of operation but `serve` is the main mode.