--- a/README.md Mon Nov 09 21:11:29 2020 -0600
+++ b/README.md Thu Nov 12 00:53:46 2020 -0600
@@ -1,21 +1,23 @@
-hgkeeper is an server for [mercurial](https://www.mercurial-scm.org/)+[  ](https://issues.imfreedom.org/issues/HGKEEPER?u=1) +HGKeeper is an server for [mercurial](https://www.mercurial-scm.org/) repositories. It provides access control for SSH access and public HTTP
-Its original design is to be run in a container, but there are plans to make-it run stand-alone as well.+It was originally designed to be run in a container but recently support has +been added to run it from an existing openssh-server. -hgkeeper is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE version 3.+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](https://issues.imfreedom.org/issues/HGKEEPER).+[issue tracker](https://issues.imfreedom.org/issues/HGKEEPER?u=1). @@ -37,9 +39,9 @@
-The initial setup of hgkeeper has a few steps. Since hgkeeper is an SSH server+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.+`hgkeeper` repository which contains the configuration for your install. @@ -61,9 +63,9 @@
### 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+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 `repos/hgkeeper`.
There are some additional options which you can discover via
@@ -75,11 +77,11 @@
-The `setup` command is used to bootstrap hgkeeper. It will create the-directory for the repositories as well as the hgkeeper repository.+The `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 that was created, as it details how access control works.+After initial setup, please make sure to read the `README.md` in the `hgkeeper` +admin repository that was created, as it details how access control works. @@ -88,11 +90,11 @@
-Access control is defined in the `hgkeeper` repository that is created via the-`hgkeeper setup` command. It is implemented via [casbin](https://casbin.org)-using the RBAC with deny-override model as a base. More information can be-found in the [files](setup/resources/) that are placed in the `hgkeeper`+Access control is defined in the `hgkeeper` admin repository that is created +via the `hgkeeper setup` command. It is implemented via +[casbin](https://casbin.org) using the RBAC with deny-override model as a +base. More information can be found in the [files](setup/resources/) +that are placed in the `hgkeeper` admin repository. ## Running in a Container
@@ -100,43 +102,24 @@
[rwgrim/hgkeeper](https://hub.docker.com/r/rwgrim/hgkeeper) and is updated via
-Just like running locally, running in the container is going to require atleast-one ssh host key and an hgkeeper administration repo.+Just like running locally, running in the container is going to require at +least one ssh host key and an `hgkeeper` admin repository. 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.+Once you have your ssh host keys generated you can create the `hgkeeper` admin +repository 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+the public key of the initial administrator 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-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.+We can now run the initialization setup that follows. @@ -149,11 +132,12 @@
-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.+Once this step is done you should now have a `repos` directory in your current +working directory and it should have a brand new `hgkeeper` admin repository -Now that your admin repository is all ready to go you can run hgkeeper in its+Now that your `hgkeeper` 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.
@@ -175,24 +159,24 @@
-And that's it! You can no access your instance via the hosts IP address or+And that's it! You can now 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.+that, be sure to read the `README.md` in the `hgkeeper` admin repository. -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+Once the SSH host keys and the `hgkeeper` admin 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 locally with an OpenSSH Server
There are a number of steps to integrate HGKeeper with OpenSSH Server and some
-of them vary across operating system. If you run into a case where these+of them vary across operating systems. If you run into a case where these instructions do not work for you, please reach out via the issue tracker so we
-can fix the documentation.+can help you and fix the documentation. @@ -211,19 +195,19 @@
To get HGKeeper fully running, you will need to run `hgkeeper setup` to create
-the `hgkeeper` repository as well as the initial admin user. Once this-repository is created, make sure it and it's parent directly are owned by the+the `hgkeeper` admin repository as well as the initial admin user. Once this +repository is created, make sure it and it's parent directory are owned by the `hg` user and that the `hg` user has write permission.
OpenSSH server has some very specific requirements for calling applications
directly. These requirements are that the executable as well as all of the
-directories leading to the executable must be owned by root and not writeable-by the group or other users. To deal with this, we will be installing HGKeeper-into `/usr/local/bin`. This directory should fulfill all of the those-requirements. So just `sudo cp hgkeeper /usr/local/bin` and make sure that-it is owned by root with a file mode of `755`.+directories leading up to the executable must be owned by root and not +writeable by the group or other users. To deal with this, we will be +installing HGKeeper into `/usr/local/bin`. This directory should fulfill all +of the those requirements. So just `sudo cp hgkeeper /usr/local/bin/` and +make sure that it is owned by `root` with a file mode of `755`. ### Configuring OpenSSH Server
@@ -242,7 +226,24 @@
AuthorizedKeysCommandUser hg
-Once you've created the file, you'll need to restart OpenSSH Server. This is-usually done via `service restart ssh` but may vary based on your operating+Once you've created the file, you'll need to reload OpenSSH Server. This is +usually done via `service ssh reload` but may vary based on your operating +Once you've reloaded OpenSSH Server you should be able to clone the `hgkeeper` +admin repository with `hg clone ssh://hg@yourhostname/hgkeeper` as long the +machine you're cloning from has the private key that you added as your initial +## Creating Respositories +Creating a new repository in HGKeeper is just the same as using mercurial over +SSH. That is, you can use the `hg init` command with a path to HGKeeper. As +long as you have init permission for the path `HGKeeper` will create an empty +For example, if you wanted to create a new repository named +`myteam/new-project-1`, you would do so with +`hg init ssh://hg@my-hgkeeper-domain/myteam/new-project-1`. If there were no +issues, the command will exit without error and you are now free to clone it +with `hg clone ssh://hg@my-hgkeeper-domain/myteam/new-project-1`. --- a/setup/resources/model.conf Mon Nov 09 21:11:29 2020 -0600
+++ b/setup/resources/model.conf Thu Nov 12 00:53:46 2020 -0600
@@ -1,7 +1,7 @@
# This is a https://casbin.org model for implementing role based access control.
# This model is based on the priorty example from the casbin documentation. It
-# will evaluate polcies in a top to bottom approach accepting the first one that+# will evaluate policies in a top to bottom approach accepting the first one that # matches. This means that you have to be careful when defining your policies.
# Say you would like to disable public access by default but then grant it to
