This project is designed to work in combination with NixOS.
+
This project is designed to work in combination with the Linux distribution NixOS or nix-darwin on macOS.
In this documentation, we expect the reader to be already familiar with the base operating system, and introduce how to compose it with our own extensions.
-
Finding your way around
-
This project exports four big categories of NixOS modules which are useful to define a server configuration:
-
-
Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
-
Machine hardware - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
-
Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
-
Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
-
-
Example
-
Combining all of those together, here is how your flake.nix might look like, to deploy a GitHub Actions runner on Hetzner:
-
{
-description="My machines flakes";
-inputs={
- srvos.url="github:nix-community/srvos";
-# Use the version of nixpkgs that has been tested to work with SrvOS
-# Alternatively we also support the latest nixos release and unstable
- nixpkgs.follows="srvos/nixpkgs";
-};
-outputs={ self, nixpkgs, srvos }:{
- nixosConfigurations.myHost= nixpkgs.lib.nixosSystem {
-system="x86_64-linux";
-modules=[
-# This machine is a server
- srvos.nixosModules.server
-# Deployed on the AMD Hetzner hardware
- srvos.nixosModules.hardware-hetzner-amd
-# Configured with extra terminfos
- srvos.nixosModules.mixins-terminfo
-# And designed to run the GitHub Actions runners
- srvos.nixosModules.roles-github-actions-runner
-# Finally add your configuration here
-./myHost.nix
-];
-};
-};
-}
-
-
Continue
-
Now that we have gone over the high-level details, you should have an idea of how to use this project.
This project exports four big categories of NixOS modules which are useful to define a server configuration:
+
+
Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
+
Machine hardware - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
+
Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
+
Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
+
+
Example
+
Combining all of those together, here is how your flake.nix might look like, to deploy a GitHub Actions runner on Hetzner:
+
{
+description="My machines flakes";
+inputs={
+ srvos.url="github:nix-community/srvos";
+# Use the version of nixpkgs that has been tested to work with SrvOS
+# Alternatively we also support the latest nixos release and unstable
+ nixpkgs.follows="srvos/nixpkgs";
+};
+outputs={ self, nixpkgs, srvos }:{
+ nixosConfigurations.myHost= nixpkgs.lib.nixosSystem {
+system="x86_64-linux";
+modules=[
+# This machine is a server
+ srvos.nixosModules.server
+# Deployed on the AMD Hetzner hardware
+ srvos.nixosModules.hardware-hetzner-amd
+# Configured with extra terminfos
+ srvos.nixosModules.mixins-terminfo
+# And designed to run the GitHub Actions runners
+ srvos.nixosModules.roles-github-actions-runner
+# Finally add your configuration here
+./myHost.nix
+];
+};
+};
+}
+
+
Continue
+
Now that we have gone over the high-level details, you should have an idea of how to use this project.
Enables a generic telegraf configuration. See Mic's dotfiles for monitoring rules targeting this telegraf configuration.
+
Enables a generic telegraf configuration. nixosModules.mixins-prometheus for monitoring rules targeting this telegraf configuration.
+
nixosModules.mixins-terminfo
+
Extends the terminfo database with often used terminal emulators.
+Terminfo is used by terminal applications to interfere supported features in the terminal.
+This is useful when connecting to a server via SSH.
+
nixosModules.mixins-prometheus
+
Enables a Prometheus and configures it with a set of alert rules targeting our nixosModules.mixins-prometheus module.
nixosModules.mixins-nginx
Configure Nginx with recommended settings. Is quite useful when using nginx as a reverse-proxy on the machine to other services.
SrvOS is a collection of NixOS modules that are optimized for servers. They includes many lessons that we gained over the years while deploying servers for our customers. As we like to share, we hope that this project will be useful to you.
To get started, start by reading the introductory tutorial, then check the User Guide for more information.
"},{"location":"faq/","title":"FAQ","text":"
Some questions and answers that haven't been integrated in the documentation yet.
"},{"location":"faq/#what-version-of-nixos-should-i-use","title":"What version of NixOS should I use?","text":"
SrvOS is currently tested against nixos-unstable and the latest NixOS release. SrvOS itself is automatically updated and tested against the latest version of that channel once a week.
If you want to make sure to use a tested version, use the \"follows\" mechanisms of Nix flakes to pull the same version as the one of SrvOS:
{\n inputs.srvos.url = \"github:nix-community/srvos\";\n # Use the version of nixpkgs that has been tested to work with SrvOS\n inputs.nixpkgs.follows = \"srvos/nixpkgs\";\n}\n
"},{"location":"getting_started/","title":"Getting Started with SrvOS","text":"
This project is designed to work in combination with NixOS.
In this documentation, we expect the reader to be already familiar with the base operating system, and introduce how to compose it with our own extensions.
"},{"location":"getting_started/#finding-your-way-around","title":"Finding your way around","text":"
This project exports four big categories of NixOS modules which are useful to define a server configuration:
Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
Machine hardware - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
Combining all of those together, here is how your flake.nix might look like, to deploy a GitHub Actions runner on Hetzner:
{\n description = \"My machines flakes\";\n inputs = {\n srvos.url = \"github:nix-community/srvos\";\n # Use the version of nixpkgs that has been tested to work with SrvOS\n # Alternatively we also support the latest nixos release and unstable\n nixpkgs.follows = \"srvos/nixpkgs\";\n };\n outputs = { self, nixpkgs, srvos }: {\n nixosConfigurations.myHost = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n # This machine is a server\n srvos.nixosModules.server\n # Deployed on the AMD Hetzner hardware\n srvos.nixosModules.hardware-hetzner-amd\n # Configured with extra terminfos\n srvos.nixosModules.mixins-terminfo\n # And designed to run the GitHub Actions runners\n srvos.nixosModules.roles-github-actions-runner\n # Finally add your configuration here\n ./myHost.nix\n ];\n };\n };\n}\n
GitHub Action Runners are processes that execute the automated jobs you specify in your GitHub Actions workflows. These runners can be hosted on GitHub-hosted infrastructure or your infrastructure. Self-hosted runners run for your project only and are available at no additional cost.
This article looks at how to install a GitHub runner in your own NixOS infrastructure, making sure the environment is scalable and secure.
We have built a NixOS module that installs one or more self-hosted github action runner, along with a cachix watch store service with the most secure defaults.
NOTE: if you intend to run NixOS VM tests you must ensure your hosting provider supports nested virtualization or use bare-metal hosts, otherwise your tests will take a long time to execute.
In order to use a self-hosted GitHub action runner, you will need to register the runner with your GitHub account or organization. There are three different ways a self hosted runner can register itself on GitHub:
Using a Registration token
Using a Personal Authentication token
Using a Github app
In this document, I will describe the most secure option: how to connect using a new GitHub App in your organization.
To ensure that you have complete control over the permissions that the app requires, you should create your own GitHub Application.
First, go to the setting page of your organization: https://github.com/organizations/<YOUR ORGANIZATION>/settings/apps
Click on New GitHub App.
In \"GitHub App name\" type <YOUR ORGANISATION> App for GitHub runners.
In \"Homepage\" fill in your project URL. It is required but won't be used hereafter.
Unselect Expire user authorization tokens.
Unselect Active in the \"Webhook\" section.
In the \"Organization permissions\" select Read and write next to the \"Self-hosted runner\" permission
Click on Create GitHub App
Once the app is created, the app's settings page will be presented. Scroll to the Private keys section and click the button labeled Generate a private key. You should save securely the generated PEM encoded private key. You will need that private key when you configure the CI. You should also save the generated GitHub App Id.
Once created, you should also limit the usage of this github app to your CI hosts public IPs (ipv4 and ipv6).
The application can be now be installed in your organization:
Go to https://github.com/organizations/<YOUR ORGANIZATION>/settings/apps
Click on the Edit button for your newly created GitHub app
Click on Install App and choose to install it on your organization
You can now use the NixOS role to install and configure the GitHub self hosted runner in your NixOS CI host.
If someone else is configuring the runner for you, you will need to provide him the the generated PEM encoded private key and the GitHub App Id.
You can find more information in the Official GitHub App creation documentation.
"},{"location":"github_actions_runner/#using-the-nixos-module","title":"Using the NixOS module","text":"
The module has been created as a role. Roles are used to define the specific purpose of a node, making it easy to manage and scale your infrastructure.
The following options must be configured
url the full URI to your organization or your repository. This URI has to match with the location where you installed the GitHub App.
count the number of runners you want to start on the host.
githubApp.id the Id of the GitHub App that was created.
githubApp.login the name of your organization / user where the GitHub App was registered.
githubApp.privateKeyFile the path to the file containing the GitHub App generated PEM encoded private key. This file should be present on the host and deployed as a secret (using sops-nix or agenix).
cachix.cacheName the name of your cachix organization.
cachix.tokenFile the path to the file containing your cachix token. This file should also be present on the host and deployed as a secret (using sops-nix or agenix).
Example of a module to configure 12 Github runners:
There are multiple ways to scale your GitHub runners, such as increasing the number of hosts or increasing the number of services on a single host. All services are completely isolated from each other, so there is no real distinction between one or the other approach. Your decision should be based on the compute/memory power your project needs.
You now have a fully functional self-hosted runner running on your NixOS infrastructure. If you need any further assistance in managing or improving your CI workflows with Nix, don't hesitate to contact us. Our team of experts is here to help you optimize your CI/CD pipelines and streamline your development process.
Enables all experimental features in nix, that are known safe to use (i.e. are only used when explicitly requested in a build). This for example unlocks use of containers in the nix sandbox.
Roles are special types of NixOS modules that are designed to take over a machine configuration.
We assume that only one role is assigned per machine.
By making this assumption, we are able to make deeper change to the machine configuration, without having to worry about potential conflicts with other roles.
Dedicates the machine to acting as a remote builder for Nix. The main use-case we have is to add more build capacity to the GitHub Actions runners, in a star fashion.
Despite this project being about servers, we wanted to dogfood the common module.
Includes everything from common
Use pipewire instead of PulseAudio.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"
Welcome!
SrvOS is a collection of NixOS modules that are optimized for servers. They includes many lessons that we gained over the years while deploying servers for our customers. As we like to share, we hope that this project will be useful to you.
To get started, start by reading the introductory tutorial, then check the User Guide for more information.
"},{"location":"faq/","title":"FAQ","text":"
Some questions and answers that haven't been integrated in the documentation yet.
"},{"location":"faq/#what-version-of-nixos-should-i-use","title":"What version of NixOS should I use?","text":"
SrvOS is currently tested against nixos-unstable and the latest NixOS release. SrvOS itself is automatically updated and tested against the latest version of that channel once a week.
If you want to make sure to use a tested version, use the \"follows\" mechanisms of Nix flakes to pull the same version as the one of SrvOS:
{\n inputs.srvos.url = \"github:nix-community/srvos\";\n # Use the version of nixpkgs that has been tested to work with SrvOS\n inputs.nixpkgs.follows = \"srvos/nixpkgs\";\n}\n
"},{"location":"getting_started/","title":"Getting Started with SrvOS","text":"
This project is designed to work in combination with the Linux distribution NixOS or nix-darwin on macOS.
In this documentation, we expect the reader to be already familiar with the base operating system, and introduce how to compose it with our own extensions.
For NixOS continue reading here, for nix-darwin/macOS read this.
GitHub Action Runners are processes that execute the automated jobs you specify in your GitHub Actions workflows. These runners can be hosted on GitHub-hosted infrastructure or your infrastructure. Self-hosted runners run for your project only and are available at no additional cost.
This article looks at how to install a GitHub runner in your own NixOS infrastructure, making sure the environment is scalable and secure.
We have built a NixOS module that installs one or more self-hosted github action runner, along with a cachix watch store service with the most secure defaults.
NOTE: if you intend to run NixOS VM tests you must ensure your hosting provider supports nested virtualization or use bare-metal hosts, otherwise your tests will take a long time to execute.
In order to use a self-hosted GitHub action runner, you will need to register the runner with your GitHub account or organization. There are three different ways a self hosted runner can register itself on GitHub:
Using a Registration token
Using a Personal Authentication token
Using a Github app
In this document, I will describe the most secure option: how to connect using a new GitHub App in your organization.
To ensure that you have complete control over the permissions that the app requires, you should create your own GitHub Application.
First, go to the setting page of your organization: https://github.com/organizations/<YOUR ORGANIZATION>/settings/apps
Click on New GitHub App.
In \"GitHub App name\" type <YOUR ORGANISATION> App for GitHub runners.
In \"Homepage\" fill in your project URL. It is required but won't be used hereafter.
Unselect Expire user authorization tokens.
Unselect Active in the \"Webhook\" section.
In the \"Organization permissions\" select Read and write next to the \"Self-hosted runner\" permission
Click on Create GitHub App
Once the app is created, the app's settings page will be presented. Scroll to the Private keys section and click the button labeled Generate a private key. You should save securely the generated PEM encoded private key. You will need that private key when you configure the CI. You should also save the generated GitHub App Id.
Once created, you should also limit the usage of this github app to your CI hosts public IPs (ipv4 and ipv6).
The application can be now be installed in your organization:
Go to https://github.com/organizations/<YOUR ORGANIZATION>/settings/apps
Click on the Edit button for your newly created GitHub app
Click on Install App and choose to install it on your organization
You can now use the NixOS role to install and configure the GitHub self hosted runner in your NixOS CI host.
If someone else is configuring the runner for you, you will need to provide him the the generated PEM encoded private key and the GitHub App Id.
You can find more information in the Official GitHub App creation documentation.
"},{"location":"github_actions_runner/#using-the-nixos-module","title":"Using the NixOS module","text":"
The module has been created as a role. Roles are used to define the specific purpose of a node, making it easy to manage and scale your infrastructure.
The following options must be configured
url the full URI to your organization or your repository. This URI has to match with the location where you installed the GitHub App.
count the number of runners you want to start on the host.
githubApp.id the Id of the GitHub App that was created.
githubApp.login the name of your organization / user where the GitHub App was registered.
githubApp.privateKeyFile the path to the file containing the GitHub App generated PEM encoded private key. This file should be present on the host and deployed as a secret (using sops-nix or agenix).
cachix.cacheName the name of your cachix organization.
cachix.tokenFile the path to the file containing your cachix token. This file should also be present on the host and deployed as a secret (using sops-nix or agenix).
Example of a module to configure 12 Github runners:
There are multiple ways to scale your GitHub runners, such as increasing the number of hosts or increasing the number of services on a single host. All services are completely isolated from each other, so there is no real distinction between one or the other approach. Your decision should be based on the compute/memory power your project needs.
You now have a fully functional self-hosted runner running on your NixOS infrastructure. If you need any further assistance in managing or improving your CI workflows with Nix, don't hesitate to contact us. Our team of experts is here to help you optimize your CI/CD pipelines and streamline your development process.
This part of the documentation provides reference documentation for day-to-day users. Use the navigation menu to jump around.
"},{"location":"darwin/getting_started/","title":"Using SrvOS with nix-darwin","text":""},{"location":"darwin/getting_started/#finding-your-way-around","title":"Finding your way around","text":"
This project exports four big categories of NixOS modules which are useful to define a server configuration:
Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
Combining all of those together, here is how your flake.nix might look like, to deploy a GitHub Actions runner on Hetzner:
{\n description = \"My machines flakes\";\n inputs = {\n srvos.url = \"github:nix-community/srvos/darwin-support\";\n # Use the version of nixpkgs that has been tested to work with SrvOS\n # Alternatively we also support the latest nixos release and unstable\n nixpkgs.follows = \"srvos/nixpkgs\";\n nix-darwin.url = \"github:LnL7/nix-darwin\";\n nix-darwin.inputs.nixpkgs.follows = \"srvos/nixpkgs\";\n };\n outputs = { srvos, nix-darwin, ... }: {\n darwinConfigurations.myHost = nix-darwin.lib.darwinSystem {\n modules = [\n # This machine is a server (i.e. CI runner)\n srvos.darwinModules.server\n # If a machine is a workstation or laptop, use this instead\n # srvos.darwinModules.desktop\n\n # Configured with extra terminfos\n srvos.darwinModules.mixins-terminfo\n # Finally add your configuration here\n ./myHost.nix\n ];\n };\n };\n}\n
Extends the terminfo database with often used terminal emulators. Terminfo is used by terminal applications to interfere supported features in the terminal. This is useful when connecting to a server via SSH.
"},{"location":"nixos/getting_started/","title":"Using SrvOS on NixOS","text":""},{"location":"nixos/getting_started/#finding-your-way-around","title":"Finding your way around","text":"
This project exports four big categories of NixOS modules which are useful to define a server configuration:
Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
Machine hardware - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
Combining all of those together, here is how your flake.nix might look like, to deploy a GitHub Actions runner on Hetzner:
{\n description = \"My machines flakes\";\n inputs = {\n srvos.url = \"github:nix-community/srvos\";\n # Use the version of nixpkgs that has been tested to work with SrvOS\n # Alternatively we also support the latest nixos release and unstable\n nixpkgs.follows = \"srvos/nixpkgs\";\n };\n outputs = { self, nixpkgs, srvos }: {\n nixosConfigurations.myHost = nixpkgs.lib.nixosSystem {\n system = \"x86_64-linux\";\n modules = [\n # This machine is a server\n srvos.nixosModules.server\n # Deployed on the AMD Hetzner hardware\n srvos.nixosModules.hardware-hetzner-amd\n # Configured with extra terminfos\n srvos.nixosModules.mixins-terminfo\n # And designed to run the GitHub Actions runners\n srvos.nixosModules.roles-github-actions-runner\n # Finally add your configuration here\n ./myHost.nix\n ];\n };\n };\n}\n
Extends the terminfo database with often used terminal emulators. Terminfo is used by terminal applications to interfere supported features in the terminal. This is useful when connecting to a server via SSH.
Enables all experimental features in nix, that are known safe to use (i.e. are only used when explicitly requested in a build). This for example unlocks use of containers in the nix sandbox.
Roles are special types of NixOS modules that are designed to take over a machine configuration.
We assume that only one role is assigned per machine.
By making this assumption, we are able to make deeper change to the machine configuration, without having to worry about potential conflicts with other roles.
Dedicates the machine to acting as a remote builder for Nix. The main use-case we have is to add more build capacity to the GitHub Actions runners, in a star fashion.