diff --git a/README.md b/README.md index 0f122ef..3cb484c 100644 --- a/README.md +++ b/README.md @@ -4,38 +4,61 @@ ![](https://raw.githubusercontent.com/numtide/nixos-anywhere/main/docs/logo.png) -Setting up a new machine is time-consuming, and becomes complicated when it needs to be done remotely. If you're installing NixOS, the **nixos-anywhere** (formerly known as **nixos-remote**) tool allows you to pre-configure the whole process including: +Setting up a new machine is time-consuming, and becomes complicated when it +needs to be done remotely. If you're installing NixOS, the **nixos-anywhere** +(formerly known as **nixos-remote**) tool allows you to pre-configure the whole +process including: - Disk partitioning and formatting - Configuring and installing either NixOS or SrvOS - Installing additional files and software -You can then initiate an unattended installation with a single CLI command. Since **nixos-anywhere** can access the new machine using SSH, it's ideal for remote installations. +You can then initiate an unattended installation with a single CLI command. +Since **nixos-anywhere** can access the new machine using SSH, it's ideal for +remote installations. -Once you have initiated the command, there is no need to 'babysit' the installation. It all happens automatically. +Once you have initiated the command, there is no need to 'babysit' the +installation. It all happens automatically. -You can use the stored configuration to repeat the same installation if you need to. +You can use the stored configuration to repeat the same installation if you need +to. ## Overview -If you have machines on a mix of platforms, you'll need a common installation solution that works anywhere. **nixos-anywhere** is ideal in this situation. +If you have machines on a mix of platforms, you'll need a common installation +solution that works anywhere. **nixos-anywhere** is ideal in this situation. -**nixos-anywhere** can be used equally well for cloud servers, bare metal servers such as Hetzner, and local servers accessible via a LAN. You can create standard configurations, and use the same configuration to create identical servers anywhere. +**nixos-anywhere** can be used equally well for cloud servers, bare metal +servers such as Hetzner, and local servers accessible via a LAN. You can create +standard configurations, and use the same configuration to create identical +servers anywhere. -You first create Nix configurations to specify partitioning, formatting and NixOS configurations. Further options can be controlled by a flake and by run-time switches. +You first create Nix configurations to specify partitioning, formatting and +NixOS configurations. Further options can be controlled by a flake and by +run-time switches. Once the configuration has been created, a single command will: - Connect to the remote server via SSH -- Detect whether a NixOS installer is present; if not, it will use the Linux `kexec` tool to boot into a Nixos installer. -- Use the [disko](https://github.com/nix-community/disko) tool to partition and format the hard drive +- Detect whether a NixOS installer is present; if not, it will use the Linux + `kexec` tool to boot into a Nixos installer. +- Use the [disko](https://github.com/nix-community/disko) tool to partition and + format the hard drive - Install NixOS - Optionally install any Nix packages and other software required. - Optionally copy additional files to the new machine -It's also possible to use **nixos-anywhere** to simplify the installation on a machine that has no current operating system, first booting from a NixOS installer image. This feature is described in the [how-to guide](./docs/how_to.md#installing-on-a-machine-with-no-operating-system). It's useful because you can pre-configure your required software and preferences, and build the new machine with a single command. +It's also possible to use **nixos-anywhere** to simplify the installation on a +machine that has no current operating system, first booting from a NixOS +installer image. This feature is described in the +[how-to guide](./docs/how_to.md#installing-on-a-machine-with-no-operating-system). +It's useful because you can pre-configure your required software and +preferences, and build the new machine with a single command. -**Important Note:** Never use a production server as the target. It will be completely overwritten and all data lost. This tool should only be used for commissioning a new computer or repurposing an old machine once all important data has been migrated. +**Important Note:** Never use a production server as the target. It will be +completely overwritten and all data lost. This tool should only be used for +commissioning a new computer or repurposing an old machine once all important +data has been migrated. ## Prerequisites @@ -43,16 +66,24 @@ It's also possible to use **nixos-anywhere** to simplify the installation on a m - - Can be any Linux machine with Nix installed, or a NixOS machine. - Target Machine: - - Unless you're using the option to boot from a NixOS installer image, or providing your own `kexec` image, it must be running x86-64 Linux with kexec support. Most x86_64 Linux systems do have kexec support. By providing your own [image](./docs/how_to.md#using-your-own-kexec-image) you can also perform kexec for other architectures eg aarch64 + - Unless you're using the option to boot from a NixOS installer image, or + providing your own `kexec` image, it must be running x86-64 Linux with kexec + support. Most x86_64 Linux systems do have kexec support. By providing your + own [image](./docs/how_to.md#using-your-own-kexec-image) you can also + perform kexec for other architectures eg aarch64 - Must have at least 1.5 GB of RAM, excluding swap. ## How to use nixos-anywhere -Here’s  a quick summary of how to use **nixos-anywhere**. You can find more information in the [product documentation](./docs). +Here’s  a quick summary of how to use **nixos-anywhere**. You can find more +information in the [product documentation](./docs). -The tool doesn't need to be installed, since it can be run directly from this repository. +The tool doesn't need to be installed, since it can be run directly from this +repository. -First create a repo that includes the disk configuration and a [flake](https://nixos.wiki/wiki/Flakes) to configure your options. This example assumes that flakes have been enabled on your source machine. +First create a repo that includes the disk configuration and a +[flake](https://nixos.wiki/wiki/Flakes) to configure your options. This example +assumes that flakes have been enabled on your source machine. Here’s an example of a simple disk configuration: @@ -104,7 +135,10 @@ Here’s an example of a simple disk configuration: } ``` -The [disko repository](https://github.com/nix-community/disko/tree/master/example) has several examples of disk configurations. You can adapt them to our own needs. +The +[disko repository](https://github.com/nix-community/disko/tree/master/example) +has several examples of disk configurations. You can adapt them to our own +needs. A simple flake may look like this: @@ -149,35 +183,48 @@ A simple flake may look like this: } ``` -Once you’ve created the disk configuration and the flake, you can run the tool with a single nix command, which may look like this: +Once you’ve created the disk configuration and the flake, you can run the tool +with a single nix command, which may look like this: ``` nix run github:numtide/nixos-anywhere -- --flake github:JillThornhill/flakes-example#hetzner-cloud root@135.181.254.201 ``` -Note that this command references the URL of your flake, in this case github:JillThornhill/flakes-example, together with the name of the system #hetzner-cloud, as highlighted by the comment in the sample flake. +Note that this command references the URL of your flake, in this case +github:JillThornhill/flakes-example, together with the name of the system +#hetzner-cloud, as highlighted by the comment in the sample flake. -The [Quickstart Guide](./docs/Quickstart.md) gives more information on how to run **nixos-anywhere** in its simplest form. For more specific instructions to suit individual requirements, see the [How To Guide](./docs/how_to.md). +The [Quickstart Guide](./docs/Quickstart.md) gives more information on how to +run **nixos-anywhere** in its simplest form. For more specific instructions to +suit individual requirements, see the [How To Guide](./docs/how_to.md). # Further Reading -@tfc has written a walkthrough on how use **nixos-anywhere** to bootstrap hetzner cloud servers as well as dedicated machines on his [blog](https://galowicz.de/2023/04/05/single-command-server-bootstrap/): +@tfc has written a walkthrough on how use **nixos-anywhere** to bootstrap +hetzner cloud servers as well as dedicated machines on his +[blog](https://galowicz.de/2023/04/05/single-command-server-bootstrap/): ## Related Tools -**nixos-anywhere** makes use of the [disko](https://github.com/nix-community/disko) tool to handle the partitioning and formatting of the disks. +**nixos-anywhere** makes use of the +[disko](https://github.com/nix-community/disko) tool to handle the partitioning +and formatting of the disks. ## Licensing and Contribution details -This software is provided free under the [MIT Licence](https://opensource.org/licenses/MIT). +This software is provided free under the +[MIT Licence](https://opensource.org/licenses/MIT). -If you would like to become a contributor, please see our [contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md) +If you would like to become a contributor, please see our +[contribution guidelines.](https://github.com/numtide/docs/contribution-guidelines.md) --- -This project is supported by [Numtide](https://numtide.com/).  ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d) +This project is supported by [Numtide](https://numtide.com/). + ![Untitledpng](https://codahosted.io/docs/6FCIMTRM0p/blobs/bl-sgSunaXYWX/077f3f9d7d76d6a228a937afa0658292584dedb5b852a8ca370b6c61dabb7872b7f617e603f1793928dc5410c74b3e77af21a89e435fa71a681a868d21fd1f599dd10a647dd855e14043979f1df7956f67c3260c0442e24b34662307204b83ea34de929d) -We are a team of independent freelancers that love open source.  We help our customers make their project lifecycles more efficient by: +We are a team of independent freelancers that love open source.  We help our +customers make their project lifecycles more efficient by: - Providing and supporting useful tools such as this one - Building and deploying infrastructure, and offering dedicated DevOps support @@ -185,4 +232,5 @@ We are a team of independent freelancers that love open source.  We help our cu - Developing additional features and tools - Carrying out custom research and development. -[Contact us](https://numtide.com/contact) if you have a project in mind, or if you need help with any of our supported tools, including this one. We'd love to +[Contact us](https://numtide.com/contact) if you have a project in mind, or if +you need help with any of our supported tools, including this one. We'd love to diff --git a/docs/howtos.md b/docs/howtos.md index 1696645..53ce9c4 100644 --- a/docs/howtos.md +++ b/docs/howtos.md @@ -16,11 +16,17 @@ TODO: Still to be documented Include: -`nixos-anywhere` can detect a nixos installer if it contains the identifier `VARIANT=installer` in its `/etc/os-release` file. This is the case for the nixos-unstable installer and will be also part of nixos 23.05. If an installer is detected `nixos-anywhere` will not try to kexec into its own image. +`nixos-anywhere` can detect a nixos installer if it contains the +identifier `VARIANT=installer` in its `/etc/os-release` file. This is the case +for the nixos-unstable installer and will be also part of nixos 23.05. If an +installer is detected `nixos-anywhere` will not try to kexec into its own image. ## Using your own kexec image -By default `nixos-anywhere` will download the kexec image from [here](https://github.com/nix-community/nixos-images#kexec-tarballs). It is also possible to provide your own by using the command line switch `--kexec` to specify the image file. The image will then be uploaded prior to executing. +By default `nixos-anywhere` will download the kexec image +from [here](https://github.com/nix-community/nixos-images#kexec-tarballs). It is +also possible to provide your own by using the command line switch `--kexec` to +specify the image file. The image will then be uploaded prior to executing. ``` nixos-anywhere \ @@ -29,7 +35,9 @@ nixos-anywhere \ root@yourip ``` -This is particularly useful for distributions like aarch64-linux, where there is no pre-build image. The following example assumes that your local machine can build for aarch64-linux either natively or through a remote builder +This is particularly useful for distributions like aarch64-linux, where there is +no pre-build image. The following example assumes that your local machine can +build for aarch64-linux either natively or through a remote builder ## Using nixos-anywhere without flakes diff --git a/docs/quickstart.md b/docs/quickstart.md index 2b00181..72a552c 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,5 +1,6 @@ # Quickstart Guide: nixos-anywhere -This document describes how to use **nixos-anywhere** in its simplest case: installing NixOS on an existing Linux distribution via SSH. +This document describes how to use **nixos-anywhere** in its simplest case: +installing NixOS on an existing Linux distribution via SSH. TODO: Populate this guide diff --git a/docs/reference.md b/docs/reference.md index 191c82a..d521ede 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -67,4 +67,5 @@ nix fmt TODO: List actual error messages and meanings. Include: -If you do not have enough RAM you will see failures unpacking the initrd), this is because kexec needs to load the whole nixos into memory. +If you do not have enough RAM you will see failures unpacking the initrd), this +is because kexec needs to load the whole nixos into memory. diff --git a/flake.nix b/flake.nix index 6e1a3f1..a6a2b2c 100644 --- a/flake.nix +++ b/flake.nix @@ -32,6 +32,7 @@ programs.shellcheck.enable = true; programs.shfmt.enable = true; programs.prettier.enable = true; + settings.formatter.prettier.options = [ "--prose-wrap" "always" ]; settings.formatter.shellcheck.options = [ "-s" "bash" ]; }; formatter = config.treefmt.build.wrapper;