Improve the readme and docs

docs/advanced-config.md

@@ -0,0 +1,26 @@
+## Advanced configuration
+
+```nix
+  services.comin = {
+    enable = true;
+    remotes = [
+      {
+        name = "origin";
+        url = "https://gitlab.com/your/private-infra.git";
+	    # This is an access token to access our private repository
+        auth.access_token_path = cfg.sops.secrets."gitlab/access_token".path;
+	    # No testing branch on this remote
+        branches.testing.name = "";
+      }
+      {
+        name = "local";
+        url = "/your/local/infra/repository";
+        # We don't want to deploy the local main branch on each commit
+        branches.main.name = "main-tilia";
+	    # We want to fetch this remote every 2 seconds
+        poller.period = 2;
+      }
+    ];
+    machineId = "22823ba6c96947e78b006c51a56fd89c";
+  };
+```

docs/authentication.md

@@ -0,0 +1,8 @@
+## Authentication for private repositories
+
+### GitLab
+
+Currently, only the GitLab [personnal access
+token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
+is supported. The file path containing the access tokenfor a remote is
+provided with the attribute `comin.remotes.*.auth.access_token_path`.

docs/design.md

@@ -0,0 +1,14 @@
+## The comin commit selection algorithm
+
+The comin configuration can contains several remotes and each of these
+remotes can have a Main and Testing branches. We then need an
+algorithm to determine which commit we want to deploy.
+
+1. Fetch `Main` and `Testing` branches from poll remotes
+2. Ensure commits from these branches are not behind the last `Main` commit
+3. Get the first commit from `Main` branches (remotes are ordered in
+   the configuration) strictly on top of the reference Main Commit. If
+   not found, get the first commit equal to the reference Main Commit.
+4. Get the first Testing commit strictly on top of the previously
+   chosen Main commit ID. If not found, use the previously chosen Main
+   commit ID.

docs/howtos.md

@@ -0,0 +1,45 @@
+## How to test a configuration change
+
+By default, each machine pulls configuration from the branch
+`testing-<hostname>`. When this branch is on top of the `main` branch,
+comin deploys this configuration by running `switch-to-configuration
+test`: the bootloader configuration is not modified.
+
+To test a configuration:
+
+1. Create a `testing-<hostname>` branch in your configuration
+   repository on top of the `main` branch
+2. Add new commits to this branch and push it
+3. comin runs `switch-to-configuration test` on the configuration: the bootload is not updated
+
+Contrary to the main branch, this branch can be hard reset but always
+has to be on top of the `main` branch.
+
+To `nixos-rebuild switch` to this configuration, the `main` branch has
+to be rebased on the `testing` branch.
+
+## Iterate faster with local repository
+
+By default, comin polls remotes every 60 seconds. You could however
+add a local repository as a comin remote: comin could then poll this
+branch every second. When you commit to this repository, comin is
+starting to deploy the new configuration immediately.
+
+However, be careful because this repository could then be used by an
+attacker to update your machine.
+
+## How to migrate a configuration from a machine to another one
+
+Suppose you have a running NixOS machine and you want to move this
+configuration to another machine while preserving the same
+hostname. If you use a testing branch, both of these machines will be
+updated when changes are pushed to the testing branch. 
+
+To avoid such situation, we could set the option
+`services.comin.machineId`. If the machine where comin is running
+doesn't have this expected `machine-id` (compared to the content of
+the `/etc/machine-id` file), comin won't deploy the configuration.
+
+So, to migrate to another machine, you have to update this
+option in the `testing-<hostname>` branch in order to only deploy this
+configuration to the new machine.

readme.md

@@ -1,89 +1,44 @@
-# Comin - Deploy NixOS machines with Git push
+# comin - Git Push NixOS Machines
 
-Comin is a deployment tool working in the pull mode. Running on a
+**comin** is a deployment tool working in the pull mode. Running on a
 machine, it periodically polls Git repositories and deploys the NixOS
-configuration associated to this machine.
+configuration associated to the machine.
 
-- Git push to deploy a NixOS configuration
+## Features
+
+- Git push to deploy NixOS configurations
 - Support testing branches to try changes
-- Easy to use
-- Support multiple Git remotes
+- Poll multiple Git remotes to avoid SPOF
+- Support machines migrations
+- Fast iterations with local remotes
 
-## Getting started
+## Quick start
 
 In your `configuration.nix` file:
 
-    services.comin = {
-      enable = true;
-      remotes = [
-	    {
-	      name = "origin";
-          url = "https://gitlab.com/your/infra.git";
-        }
-	  ]
-    };
+```nix
+services.comin = {
+  enable = true;
+  remotes = [
+    {
+      name = "origin";
+      url = "https://gitlab.com/your/infra.git";
+    }
+  ]
+};
+```
 
 This enables a systemd service, which periodically pulls the `main`
 branch of the repository `https://gitlab.com/your/infra.git` and
 deploys the NixOS configuration corresponding to the machine hostname.
 
-## How to test a configuration without having to commit to main
-
-By default, each machine also pulls configuration from the branch
-`testing-<hostname>`. When this branch is on top of the `main` branch,
-Comin deploys this configuration by running `switch-to-configuration
-test`: the bootloader configuration is not modified.
-
-To test a configuration:
-
-1. Create a `testing-<hostname>` branch in your configuration
-   repository on top of the `main` branch
-2. Add new commits to this branch and push it
-3. Comin runs `switch-to-configuration test` on the  configuration
-
-Contrary to the main branch, this branch can be hard reset but always
-has to be on top of the `main` branch.
-
-To `nixos-rebuild switch` to the testing configuration, the `main`
-branch has to be rebased on the `testing` branch.
-
-## Authentication for private repositories
-
-### GitLab
-
-Currently, only the GitLab [personnal access
-token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
-is supported.
-
-- The module option `services.comin.authFile` allows to specify the
-  path of a file containing the GitLab access token.
-- The command `comin boostrap --ask-for-gitlab-access-token` allows to
-  ask for a GitLab access token to fetch the repository.
-
-## How to migrate a configuration from a machine to another one
-
-When the option `services.comin.machineId` is set, Comin only deploys
-the configuration on the machine if the option value matches the
-`/etc/machine-id` value.
-
-To migrate to another machine, it is then possible to update this option in the `testing-<hostname>` branch in order to only deploy this configuration on a the new machine.
-
-
-## Commit selection algorithm
-
-The comin configuration can contains several remotes and each of these
-remotes can have a Main and Testing branches. We then need an
-algorithm to determine which commit we want to deploy.
-
-1. Fetch Main and Testing branches from remotes
-2. Ensure commits from these branches are on top of (could be the same
-   commit) the reference Main Commit (coming from a previous
-   iteration)
-3. Get the first commit from Main branches (remotes are ordered) strictly on top of
-   the reference Main Commit. If not found, get the first commit equal
-   to the reference Main Commit.
-4. Get the first Testing commit strictly on top of the previously
-   chosen Main commit ID. If not found, use the previously chosen Main
-   commit ID.
+A new commit in the `main` branch of the repository
+`https://gitlab.com/your/infra.git` is then deployed in the next 60
+seconds.
 
+## Documentation
 
+- [Howtos](./docs/howtos.md)
+- [Advanced Configuraion](./docs/advanced-config.md)
+- [Authentication](./docs/authentication.md)
+- [Design](./docs/design.md)