mirror of
https://github.com/numtide/nixos-anywhere.git
synced 2024-10-26 12:57:16 +03:00
prettier: wrap long lines
This commit is contained in:
parent
f5646c99a0
commit
bb724e37b0
100
README.md
100
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
|
||||
|
@ -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
|
||||
|
||||
|
@ -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
|
||||
|
@ -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.
|
||||
|
@ -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;
|
||||
|
Loading…
Reference in New Issue
Block a user