Rewrite README (#67)

Increase clarity of operation procedure,
explicitly state tested hosters & OS versions,
and switch to using semantic linefeeds.
This commit is contained in:
Bryan Bennett 2021-02-08 10:33:39 -05:00 committed by GitHub
parent bdfc7b6a8d
commit 9f6428761d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

154
README.md
View file

@ -1,59 +1,73 @@
This script aims to install NixOS on Digital Ocean droplets, Vultr servers, or # NixOS-Infect
OVH Virtual Private Servers (starting from distros that these services support
out of the box).
## Source Distros ## What is this?
A script to install NixOS on non-NixOS hosts.
This script has been tested and can install NixOS from the following source distros: NixOS-Infect is so named because of the high likelihood of rendering a system inoperable.
Use with extreme caution and preferably only on newly provisioned systems.
On Digital Ocean: This script has successfully been tested on at least the follow hosting providers and plans:
- Fedora 24 x64
- Ubuntu 20.04 x64
On Vultr: * [DigitalOcean](https://www.digitalocean.com/products/droplets/)
- Ubuntu 18.10 x64 * [Hetzner Cloud](https://www.hetzner.com/cloud)
* [Vultr](https://www.vultr.com/)
* [Interserver VPS](https://www.interserver.net/vps/)
On OVH Virtual Private Servers (experimental): Should you find that it works on your hoster,
- Debian feel free to update this README and issue a pull request.
On Hetzner cloud: > *NB:* OpenVZ-based virtualization providers are known not to work with `nixos-infect` (or any other OS takeover script).
- Ubuntu 18.04 > This is core to how OpenVZ operates and cannot be resolved.
YMMV with any other hoster + image combination. ## Motivation
If you have a OpenVZ based virtualization solution then this, or any other OS takeover script will not work, this is fundamental to how OpenVZ works. Motivation for this script: nixos-assimilate should supplant this script entirely,
if it's ever completed.
nixos-in-place was quite broken when I tried it,
and also took a pretty janky approach that was substantially more complex than this
(although it supported more platforms):
it didn't install to root (/nixos instead),
left dregs of the old filesystem
(almost always unnecessary since starting from a fresh deployment),
and most importantly, simply didn't work for me!
(old system was being because grub wasnt properly reinstalled)
## Considerations ## How do I use it?
nixos-infect is so named because of the high likelihood of rendering a system 0) **Read and understand the [the script](./nixos-infect)**
inoperable. Use with caution and preferably only on newly-provisioned 1) Deploy any custom configuration you want on your host
systems. 2) Deploy your host as non-Nix Operating System.
3) Deploy an SSH key for the root user.
*WARNING NB*: This script wipes out the targeted host's root filesystem when it > *NB:* This step is important.
runs to completion. Any errors halt execution. It's advised to run with > The root user will not have a password when nixos-infect runs to completion.
`bash -x` to help debug, as often a failed run leaves the system in an > To enable root login, you *must* have an SSH key configured.
inconsistent state, requiring a rebuild (in DigitalOcean panel: Droplet
Settings -> "Destroy" -> "Rebuild from original").
## Digital Ocean 4) run the script with:
```
curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash -x
```
*TO USE:* *NB*: This script wipes out the targeted host's root filesystem when it runs to completion.
- Add any custom config you want (see notes below) Any errors halt execution.
- Deploy the droplet indicated at the top of the file, enable ipv6, add your ssh key A failure will leave the system in an inconsistent state,
- `cat customConfig.optional nixos-infect | ssh root@targethost` and so it is advised to run with `bash -x`.
Alternatively, you may utilize Digital Ocean's "user data" mechanism (found in the Web UI or HTTP API), and supply to it the following example yaml stanzas: ## Hoster notes:
### Digital Ocean
You mmay utilize Digital Ocean's "user data" mechanism (found in the Web UI or HTTP API),
and supply to it the following example yaml stanzas:
```yaml ```yaml
#cloud-config #cloud-config
runcmd: runcmd:
- curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log
``` ```
Potential tweaks:
#### Potential tweaks:
- `/etc/nixos/{,hardware-}configuration.nix`: rudimentary mostly static config - `/etc/nixos/{,hardware-}configuration.nix`: rudimentary mostly static config
- `/etc/nixos/networking.nix`, networking settings determined at runtime tweak - `/etc/nixos/networking.nix`: networking settings determined at runtime tweak if no ipv6, different number of adapters, etc.
if no ipv6, different number of adapters, etc.
```yaml ```yaml
#cloud-config #cloud-config
@ -66,39 +80,75 @@ write_files:
environment.systemPackages = with pkgs; [ vim ]; environment.systemPackages = with pkgs; [ vim ];
} }
runcmd: runcmd:
- curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIXOS_IMPORT=./host.nix NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log - curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | PROVIDER=digitalocean NIXOS_IMPORT=./host.nix NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log
``` ```
## Vultr
To set up a NixOS Vultr server, instantiate an Ubuntu box with the following "Startup Script": #### Tested on
|Distribution| Name | Status | test date|
|------------|-----------------|-----------|----------|
|CentOS |6.9 x32 | _failure_ |2020-03-30|
|CentOS |6.9 x64 | _failure_ |2020-03-30|
|CentOS |7.6 x64 | _failure_ |2020-03-30|
|CentOS |8.1 x64 |**success**|2020-03-30|
|CoreOS |2345.3.0 (stable)| _unable_ |2020-03-30|
|CoreOS |2411.1.0 (beta) | _unable_ |2020-03-30|
|CoreOS |2430.0.0 (alpha) | _unable_ |2020-03-30|
|Debian |10.3 x64 |**success**|2020-03-30|
|Debian |9.12 x64 |**success**|2020-03-30|
|Fedora |30 x64 |**success**|2020-03-30|
|Fedora |31 x64 |**success**|2020-03-30|
|FreeBSD |11.3 x64 ufs | _failure_ |2020-03-30|
|FreeBSD |11.3 x64 zfs | _failure_ |2020-03-30|
|FreeBSD |12.1 x64 ufs | _failure_ |2020-03-30|
|FreeBSD |12.1 x64 zfs | _failure_ |2020-03-30|
|RancherOS |v1.5.5 | _unable_ |2020-03-30|
|Ubuntu |16.04.6 (LTS) x32|**success**|2020-03-30|
|Ubuntu |16.04.6 (LTS) x64|**success**|2020-03-30|
|Ubuntu |18.04.3 (LTS) x64|**success**|2020-03-30|
|Ubuntu |19.10 x64 |**success**|2020-03-30|
### Vultr
To set up a NixOS Vultr server,
instantiate an Ubuntu box with the following "Startup Script":
```bash ```bash
#!/bin/sh #!/bin/sh
curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.03 bash curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash
``` ```
Allow for a few minutes over the usual Ubuntu deployment time for NixOS to download & install itself. Allow for a few minutes over the usual Ubuntu deployment time for NixOS to download & install itself.
## Hetzner cloud #### Tested on
|Distribution| Name | Status | test date| Slug | ID |
|------------|-----------------|-----------|----------|------------------|---------|
| Ubuntu | 18.10 x64 |**success**|(Unknown) | (Unknown) |(Unknown)|
Hetzner cloud works out of the box. When creating a server provide the following script as "User data" (this has been tested using Ubuntu 20.04 as a base OS).
### Hetzner cloud
Hetzner cloud works out of the box.
When creating a server provide the following script as "User data":
``` ```
#!/bin/sh #!/bin/sh
curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.03 bash 2>&1 | tee /tmp/infect.log curl https://raw.githubusercontent.com/elitak/nixos-infect/master/nixos-infect | NIX_CHANNEL=nixos-20.09 bash 2>&1 | tee /tmp/infect.log
``` ```
## Motivation #### Tested on
|Distribution| Name | Status | test date|
|------------|-----------------|-----------|----------|
|Ubuntu | 20.04 x64 |**success**|(Unknown) |
Motivation for this script: nixos-assimilate should supplant this script ### InterServer VPS
entirely, if it's ever completed. nixos-in-place was quite broken when I #### Tested on
tried it, and also took a pretty janky approach that was substantially more |Distribution| Name | Status | test date|
complex than this (although it supported more platforms): it didn't install |------------|-----------------|-----------|----------|
to root (/nixos instead), left dregs of the old filesystem (almost always |Debian | 9 |**success**|2021-01-29|
unnecessary since starting from a fresh deployment), and most importantly, |Debian | 10 |**success**|2021-01-29|
simply didn't work for me! (old system was being because grub wasnt properly |Ubuntu | 20.04 |**success**|2021-01-29|
reinstalled) |Ubuntu | 18.04 |**success**|2021-01-29|
|Ubuntu | 14.04 |**success**|2021-01-29|