mic92 / nixos-remote

Nixos Remote Documentation Page

nixos-remote

Installing Nixos on a remote machine is complicated and time-consuming. The nixos-remote tool allows you to acess a remote server via SSH, partition and format its disks and install Nixos quickly and painlessly. Since nixos-remote makes use of stored configurations, you can repeat the same installation as often as you need, using a single nix-run command for each server. This tool is ideal for setting up Nixos in the cloud.

Overview

This tool is extremely useful when using cloud services such as Google, Amazon and Hezner. You can create standard configurations, and use the same configuration to create identical servers anywhere.

The partitioning and formatting options are specified in a disk configuration file. Further options can either be controlled by run-time switches, or by using a flake.

A single run-time command will then:

• Connect to the remote server via SSH

• Use the Linux kexec tool to boot into a Nixos installer

• Use the disko tool to partition and format the hard drive

• Install Nixos

• Optionally, other NIX packages can be installed at the same time.

Important Note: Do not use a live server as the target, as it will be completely overwritten and all data lost. This tool should only be used for commissioning a new server, or repurposing an old server that contains no data that needs to be retained.

Prerequisites

• Source Server:

  • Can be any Linux or Mac server with NIX installed, or a Nixos server.

• Destination Server:

  • Must be an x86_64 Linux system with kexec support. Most x86_64 Linux systems do have kexec support.

  • Must have at least 2.5 GB of RAM, excluding swap.

How to use nixos_remote

The tool does not need to be installed, since it can be run directly from this repository.

First create a repo that includes the disk configuration file and, optionally, a flake that configures options. Samples of the disk configuration and flake files are included in the documentation. Full details of these configurations are given in the reference manual.

Once you have created these files, you can then run the tool with a single nix-run command, which may look like this:

nix run github:numtide/nixos-remote -- --flake github:JillThornhill/flakes-example#hetzner-cloud [email protected]

The Quickstart Guide gives full information on how to run nixos-remote in its simplest form. For more specific instructions to suit individual requirements, see the How-to Guide.

Licensing and Contribution details

This software is provided free under the MIT Licence.

If you would like to become a contributor, please see our contribution guidelines

Contributors

@lassulus

@Mic92

This software is brought to you courtesy of Numtide Consulting.

Numtide offers experienced consultants for hire, specializing in the following areas:

(Need a list of services)

Contact us)