From cef7b0f70f2d7f012d44d797ce01497cc624cf28 Mon Sep 17 00:00:00 2001 From: Antoine Eiche Date: Tue, 30 Jan 2024 20:54:10 +0100 Subject: [PATCH] Improve the readme and docs --- docs/advanced-config.md | 26 ++++++++++ docs/authentication.md | 8 ++++ docs/design.md | 14 ++++++ docs/howtos.md | 45 ++++++++++++++++++ readme.md | 103 +++++++++++----------------------------- 5 files changed, 122 insertions(+), 74 deletions(-) create mode 100644 docs/advanced-config.md create mode 100644 docs/authentication.md create mode 100644 docs/design.md create mode 100644 docs/howtos.md diff --git a/docs/advanced-config.md b/docs/advanced-config.md new file mode 100644 index 0000000..6c51c15 --- /dev/null +++ b/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"; + }; +``` diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 0000000..7e9b762 --- /dev/null +++ b/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`. diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..1f7668b --- /dev/null +++ b/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. diff --git a/docs/howtos.md b/docs/howtos.md new file mode 100644 index 0000000..2a17227 --- /dev/null +++ b/docs/howtos.md @@ -0,0 +1,45 @@ +## How to test a configuration change + +By default, each machine pulls configuration from the branch +`testing-`. 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-` 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-` branch in order to only deploy this +configuration to the new machine. diff --git a/readme.md b/readme.md index 8dac552..acdf004 100644 --- a/readme.md +++ b/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-`. 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-` 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-` 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)