{"id":13611728,"url":"https://github.com/zhaofengli/colmena","last_synced_at":"2025-05-14T13:03:44.895Z","repository":{"id":37044247,"uuid":"321866601","full_name":"zhaofengli/colmena","owner":"zhaofengli","description":"A simple, stateless NixOS deployment tool","archived":false,"fork":false,"pushed_at":"2025-05-05T23:10:02.000Z","size":2683,"stargazers_count":1509,"open_issues_count":128,"forks_count":81,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-05-06T00:24:11.842Z","etag":null,"topics":["deployment","nix","nixos"],"latest_commit_sha":null,"homepage":"https://colmena.cli.rs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhaofengli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-12-16T04:21:43.000Z","updated_at":"2025-05-04T14:14:05.000Z","dependencies_parsed_at":"2023-02-18T03:31:28.710Z","dependency_job_id":"7b073b8a-3ed6-48c7-9f98-53e55916fa17","html_url":"https://github.com/zhaofengli/colmena","commit_stats":{"total_commits":528,"total_committers":30,"mean_commits":17.6,"dds":"0.14962121212121215","last_synced_commit":"a6b51f5feae9bfb145daa37fd0220595acb7871e"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhaofengli%2Fcolmena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhaofengli%2Fcolmena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhaofengli%2Fcolmena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhaofengli%2Fcolmena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhaofengli","download_url":"https://codeload.github.com/zhaofengli/colmena/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149825,"owners_count":22022850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deployment","nix","nixos"],"created_at":"2024-08-01T19:02:02.298Z","updated_at":"2025-05-14T13:03:44.880Z","avatar_url":"https://github.com/zhaofengli.png","language":"Rust","funding_links":[],"categories":["Rust","Deployment Tools"],"sub_categories":["Discovery"],"readme":"# Colmena\n\n[![Matrix Channel](https://img.shields.io/badge/Matrix-%23colmena%3Anixos.org-blueviolet)](https://matrix.to/#/#colmena:nixos.org)\n[![Stable Manual](https://img.shields.io/badge/Manual-Stable-informational)](https://colmena.cli.rs/stable)\n[![Unstable Manual](https://img.shields.io/badge/Manual-Unstable-orange)](https://colmena.cli.rs/unstable)\n[![Build](https://github.com/zhaofengli/colmena/actions/workflows/build.yml/badge.svg)](https://github.com/zhaofengli/colmena/actions/workflows/build.yml)\n\nColmena is a simple, stateless [NixOS](https://nixos.org) deployment tool modeled after [NixOps](https://github.com/NixOS/nixops) and [morph](https://github.com/DBCDK/morph), written in Rust.\nIt's a thin wrapper over Nix commands like `nix-instantiate` and `nix-copy-closure`, and supports parallel deployment.\n\nNow with 100% more flakes! See *Tutorial with Flakes* below.\n\n\u003cpre\u003e\n$ \u003cb\u003ecolmena apply --on @tag-a\u003c/b\u003e\n[INFO ] Enumerating nodes...\n[INFO ] Selected 7 out of 45 hosts.\n  (...) ✅ 0s Build successful\n  \u003cb\u003esigma\u003c/b\u003e 🕗 7s copying path '/nix/store/h6qpk8rwm3dh3zsl1wlj1jharzf8aw9f-unit-haigha-agent.service' to 'ssh://root@sigma.redacted'...\n  \u003cb\u003etheta\u003c/b\u003e ✅ 7s Activation successful\n  \u003cb\u003egamma\u003c/b\u003e 🕘 8s Starting...\n  \u003cb\u003ealpha\u003c/b\u003e ✅ 1s Activation successful\n\u003cb\u003eepsilon\u003c/b\u003e 🕗 7s copying path '/nix/store/fhh4rfixny8b21l6jqzk7nqwxva5k20h-nixos-system-epsilon-20.09pre-git' to 'ssh://root@epsilon.redacted'...\n   \u003cb\u003ebeta\u003c/b\u003e 🕗 7s removing obsolete file /boot/kernels/z28ayg10kpnlrz0s2qrb9pzv82lc20s2-initrd-linux-5.4.89-initrd\n  \u003cb\u003ekappa\u003c/b\u003e ✅ 2s Activation successful\n\u003c/pre\u003e\n\n## Installation\n\n`colmena` is included in Nixpkgs beginning with 21.11.\n\nUse the following command to enter a shell environment with the `colmena` command:\n\n```bash\nnix-shell -p colmena\n```\n\n### Unstable Version\n\nTo install the latest development version to your user profile:\n\n```bash\nnix-env -if https://github.com/zhaofengli/colmena/tarball/main\n```\n\nAlternatively, if you have a local clone of the repo:\n\n```bash\nnix-env -if default.nix\n```\n\nA public binary cache is available at https://colmena.cachix.org, courtesy of Cachix.\nThis binary cache contains unstable versions of Colmena built by [GitHub Actions](https://github.com/zhaofengli/colmena/actions).\n\n## Tutorial\n\n*See Tutorial with Flakes for usage with Nix Flakes.*\n\nColmena should work with your existing NixOps and morph configurations with minimal modification.\nHere is a sample `hive.nix` with two nodes, with some common configurations applied to both nodes:\n\n```nix\n{\n  meta = {\n    # Override to pin the Nixpkgs version (recommended). This option\n    # accepts one of the following:\n    # - A path to a Nixpkgs checkout\n    # - The Nixpkgs lambda (e.g., import \u003cnixpkgs\u003e)\n    # - An initialized Nixpkgs attribute set\n    nixpkgs = \u003cnixpkgs\u003e;\n\n    # You can also override Nixpkgs by node!\n    nodeNixpkgs = {\n      node-b = ./another-nixos-checkout;\n    };\n\n    # If your Colmena host has nix configured to allow for remote builds\n    # (for nix-daemon, your user being included in trusted-users)\n    # you can set a machines file that will be passed to the underlying\n    # nix-store command during derivation realization as a builders option.\n    # For example, if you support multiple orginizations each with their own\n    # build machine(s) you can ensure that builds only take place on your\n    # local machine and/or the machines specified in this file.\n    # machinesFile = ./machines.client-a;\n  };\n\n  defaults = { pkgs, ... }: {\n    # This module will be imported by all hosts\n    environment.systemPackages = with pkgs; [\n      vim wget curl\n    ];\n\n    # By default, Colmena will replace unknown remote profile\n    # (unknown means the profile isn't in the nix store on the\n    # host running Colmena) during apply (with the default goal,\n    # boot, and switch).\n    # If you share a hive with others, or use multiple machines,\n    # and are not careful to always commit/push/pull changes\n    # you can accidentaly overwrite a remote profile so in those\n    # scenarios you might want to change this default to false.\n    # deployment.replaceUnknownProfiles = true;\n  };\n\n  host-a = { name, nodes, ... }: {\n    # The name and nodes parameters are supported in Colmena,\n    # allowing you to reference configurations in other nodes.\n    networking.hostName = name;\n    time.timeZone = nodes.host-b.config.time.timeZone;\n\n    boot.loader.grub.device = \"/dev/sda\";\n    fileSystems.\"/\" = {\n      device = \"/dev/sda1\";\n      fsType = \"ext4\";\n    };\n  };\n\n  host-b = {\n    # Like NixOps and morph, Colmena will attempt to connect to\n    # the remote host using the attribute name by default. You\n    # can override it like:\n    deployment.targetHost = \"host-b.mydomain.tld\";\n\n    # It's also possible to override the target SSH port.\n    # For further customization, use the SSH_CONFIG_FILE\n    # environment variable to specify a ssh_config file.\n    deployment.targetPort = 1234;\n\n    # Override the default for this target host\n    deployment.replaceUnknownProfiles = false;\n\n    # You can filter hosts by tags with --on @tag-a,@tag-b.\n    # In this example, you can deploy to hosts with the \"web\" tag using:\n    #    colmena apply --on @web\n    # You can use globs in tag matching as well:\n    #    colmena apply --on '@infra-*'\n    deployment.tags = [ \"web\" \"infra-lax\" ];\n\n    time.timeZone = \"America/Los_Angeles\";\n\n    boot.loader.grub.device = \"/dev/sda\";\n    fileSystems.\"/\" = {\n      device = \"/dev/sda1\";\n      fsType = \"ext4\";\n    };\n  };\n}\n```\n\nThe full set of options can be found in [the manual](https://colmena.cli.rs/unstable/reference).\nRun `colmena build` in the same directory to build the configuration, or do `colmena apply` to build and deploy it to all nodes.\n\n## Tutorial with Flakes\n\nTo use with Nix Flakes, create `outputs.colmenaHive` in your `flake.nix`.\n\nHere is a short example:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:NixOS/nixpkgs/nixos-unstable\";\n    colmena.url = \"github:zhaofengli/colmena\";\n  };\n  outputs = { nixpkgs, colmena, ... }: {\n    colmenaHive = colmena.lib.makeHive {\n      meta = {\n        nixpkgs = import nixpkgs {\n          system = \"x86_64-linux\";\n          overlays = [];\n        };\n      };\n\n      # Also see the non-Flakes hive.nix example above.\n      host-a = { name, nodes, pkgs, ... }: {\n        boot.isContainer = true;\n        time.timeZone = nodes.host-b.config.time.timeZone;\n      };\n      host-b = {\n        deployment = {\n          targetHost = \"somehost.tld\";\n          targetPort = 1234;\n          targetUser = \"luser\";\n        };\n        boot.isContainer = true;\n        time.timeZone = \"America/Los_Angeles\";\n      };\n    };\n  };\n}\n```\n\nThe full set of options can be found in [the manual](https://colmena.cli.rs/unstable/reference).\nRun `colmena build` in the same directory to build the configuration, or do `colmena apply` to build and deploy it to all nodes.\n\n### Migrating to Direct Flake Evaluation\n\n\u003e error: flake 'git+file:///path/to/flake' does not provide attribute 'packages.x86_64-linux.colmenaHive', 'legacyPackages.x86_64-linux.colmenaHive' or 'colmenaHive'\n\nColmena now uses `nix eval` to evaluate flakes.\nYour flake needs to depend on Colmena itself as an input and expose a new output called `colmenaHive`:\n\n```diff\n {\n   inputs = {\n+    # ADDED: Colmena input\n+    colmena.url = \"github:zhaofengli/colmena\";\n\n     # ... Rest of configuration ...\n   };\n   outputs = { self, colmena, ... }: {\n+    # ADDED: New colmenaHive output\n+    colmenaHive = colmena.lib.makeHive self.outputs.colmena;\n\n     # Your existing colmena output\n     colmena = {\n       # ... Rest of configuration ...\n     };\n   };\n }\n```\n\n## Manual\n\nRead [the Colmena Manual](https://colmena.cli.rs).\n\n## Environment Variables\n\n- `SSH_CONFIG_FILE`: Path to a `ssh_config` file\n\n## Current Limitations\n\n- It's required to use SSH keys to log into the remote hosts, and interactive authentication will not work.\n- Error reporting is lacking.\n\n## Licensing\n\nColmena is available under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhaofengli%2Fcolmena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhaofengli%2Fcolmena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhaofengli%2Fcolmena/lists"}