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
OVH Virtual Private Servers (starting from distros that these services support
out of the box).
# NixOS-Infect
## 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:
- Fedora 24 x64
- Ubuntu 20.04 x64
This script has successfully been tested on at least the follow hosting providers and plans:
On Vultr:
- Ubuntu 18.10 x64
* [DigitalOcean](https://www.digitalocean.com/products/droplets/)
* [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):
- Debian
Should you find that it works on your hoster,
feel free to update this README and issue a pull request.
On Hetzner cloud:
- Ubuntu 18.04
> *NB:* OpenVZ-based virtualization providers are known not to work with `nixos-infect` (or any other OS takeover script).
> 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
inoperable. Use with caution and preferably only on newly-provisioned
systems.
0) **Read and understand the [the script](./nixos-infect)**
1) Deploy any custom configuration you want on your host
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
runs to completion. Any errors halt execution. It's advised to run with
`bash -x` to help debug, as often a failed run leaves the system in an
inconsistent state, requiring a rebuild (in DigitalOcean panel: Droplet
Settings -> "Destroy" -> "Rebuild from original").
> *NB:* This step is important.
> The root user will not have a password when nixos-infect runs to completion.
> To enable root login, you *must* have an SSH key configured.
## 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:*
- Add any custom config you want (see notes below)
- Deploy the droplet indicated at the top of the file, enable ipv6, add your ssh key
- `cat customConfig.optional nixos-infect | ssh root@targethost`
*NB*: This script wipes out the targeted host's root filesystem when it runs to completion.
Any errors halt execution.
A failure will leave the system in an inconsistent state,
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
#cloud-config
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/networking.nix`, networking settings determined at runtime tweak
if no ipv6, different number of adapters, etc.
- `/etc/nixos/networking.nix`: networking settings determined at runtime tweak if no ipv6, different number of adapters, etc.
```yaml
#cloud-config
@ -66,39 +80,75 @@ write_files:
environment.systemPackages = with pkgs; [ vim ];
}
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
#!/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.
## 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
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
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)
### InterServer VPS
#### Tested on
|Distribution| Name | Status | test date|
|------------|-----------------|-----------|----------|
|Debian | 9 |**success**|2021-01-29|
|Debian | 10 |**success**|2021-01-29|
|Ubuntu | 20.04 |**success**|2021-01-29|
|Ubuntu | 18.04 |**success**|2021-01-29|
|Ubuntu | 14.04 |**success**|2021-01-29|