lix-project/lix-installer
16
4
Fork 4
Code Issues 23 Code Review (Gerrit) Projects Activity

Readme cutificiation (#618)

Browse source 
* Engage README cutification subroutine

* Trimming
This commit is contained in:
Ana Hobden 2023-09-06 08:12:47 -07:00 committed by GitHub
parent 8395b40223
commit d7412ba096
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 103 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

185
README.md
View file

@ -1,18 +1,16 @@
# Install Nix with flakes using the Determinate Nix Installer
_🎉 Celebrating over 500,000 successful installations! 🎉_
# The Determinate Nix Installer
[![Crates.io](https://img.shields.io/crates/v/nix-installer)](https://crates.io/crates/nix-installer)
[![Docs.rs](https://img.shields.io/docsrs/nix-installer)](https://docs.rs/nix-installer/latest/nix_installer/)
`nix-installer`, the fast and reliable Nix installer.
A fast, friendly, and reliable tool to help you use Nix with Flakes everywhere.
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
The `nix-installer` tool is ready to use in a number of environments:
The `nix-installer` has successfully completed over 500,000 installs in a number of environments, including [Github Actions](#as-a-github-action):
| Platform | Multi User | `root` only | Maturity |
|------------------------------|:------------------:|:-----------:|:-----------------:|
@ -27,32 +25,6 @@ The `nix-installer` tool is ready to use in a number of environments:
> **Note**
> On **MacOS only**, removing users and/or groups may fail if there are no users who are logged in graphically.
## Installation Differences
Differing from the upstream [Nix](https://github.com/NixOS/nix) installer scripts:
* In `nix.conf`:
+ the `auto-allocate-uids`, `nix-command` and `flakes` features are enabled
+ `bash-prompt-prefix` is set
+ `auto-optimise-store` is set to `true` (On Linux only)
* `extra-nix-path` is set to `nixpkgs=flake:nixpkgs`
* `auto-allocate-uids` is set to `true`. (On Linux only)
* an installation receipt (for uninstalling) is stored at `/nix/receipt.json` as well as a copy of the install binary at `/nix/nix-installer`
* `nix-channel --update` is not run, `~/.nix-channels` is not provisioned
* `NIX_SSL_CERT_FILE` is set in the various shell profiles if the `ssl-cert-file` argument is used.
## Motivations
The upstream scripts do a good job, however they are difficult to maintain.
Subtle differences in the shell implementations and certain characteristics of Bash scripts make it difficult to make meaningful changes to the installer.
The Determinate Nix installer has numerous advantages:
* keeping an installation receipt for easy uninstallation
* offering users a chance to review an accurate, calculated install plan
* having 'planners' which can create appropriate install plans for complicated targets
* offering users with a failing install the chance to do a best-effort revert
* improving performance by maximizing parallel operations
## Usage
@ -67,12 +39,9 @@ Or, to download a platform specific Installer binary yourself:
```bash
$ curl -sL -o nix-installer https://install.determinate.systems/nix/nix-installer-x86_64-linux
$ chmod +x nix-installer
$ ./nix-installer
```
> **Note**
> `nix-installer` will elevate itself if needed using `sudo`.
> If you use `doas` or `please` you may need to elevate `nix-installer` yourself.
`nix-installer` installs Nix by following a *plan* made by a *planner*. Review the available planners:
```bash
@ -127,7 +96,7 @@ $ NIX_BUILD_GROUP_NAME=nixbuilder ./nix-installer install linux-multi --nix-buil
```
## Uninstalling
### Uninstalling
You can remove a `nix-installer`-installed Nix by running
@ -136,7 +105,7 @@ You can remove a `nix-installer`-installed Nix by running
```
## As a Github Action
### As a Github Action
You can use the [`nix-installer-action`](https://github.com/DeterminateSystems/nix-installer-action) Github Action like so:
@ -158,7 +127,7 @@ jobs:
run: nix build .
```
## Without systemd (Linux only)
### Without systemd (Linux only)
> **Warning**
> When `--init none` is used, _only_ `root` or users who can elevate to `root` privileges can run Nix:
@ -173,7 +142,7 @@ If you don't use [systemd], you can still install Nix by explicitly specifying t
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install linux --init none
```
## In a container
### In a container
In Docker/Podman containers or WSL2 instances where an init (like `systemd`) is not present, pass `--init none`.
@ -236,15 +205,29 @@ podman rmi $IMAGE
On some container tools, such as `docker`, `sandbox = false` can be omitted. Omitting it will negatively impact compatibility with container tools like `podman`.
## In WSL2
### In WSL2
We **strongly recommend** [enabling systemd](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd), then installing Nix as normal:
If [systemd is enabled](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd) it's possible to install Nix as normal using the command at the top of this document:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
```
If systemd is not enabled, pass `--init none` at the end of the command:
If [WSLg][wslg] is enabled, you can do things like open a Linux Firefox from Windows on Powershell:
```powershell
wsl nix run nixpkgs#firefox
```
To use some OpenGL applications, you can use [`nixGL`][nixgl] (note that some applications, such as `blender`, may not work):
```powershell
wsl nix run --impure github:guibou/nixGL nix run nixpkgs#obs-studio
```
If enabling system is not an option, pass `--init none` at the end of the command:
> **Warning**
> When `--init none` is used, _only_ `root` or users who can elevate to `root` privileges can run Nix:
@ -258,7 +241,7 @@ If systemd is not enabled, pass `--init none` at the end of the command:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install linux --init none
```
## Skip confirmation
### Skip confirmation
If you'd like to bypass the confirmation step, you can apply the `--no-confirm` flag:
@ -268,6 +251,54 @@ curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix
This is especially useful when using the installer in non-interactive scripts.
## Quirks
While `nix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
### Using MacOS remote SSH builders, Nix binaries are not on `$PATH`
When connecting to a Mac remote SSH builder users may sometimes see this error:
```bash
$ nix store ping --store "ssh://$USER@$HOST"
Store URL: ssh://$USER@$HOST
zsh:1: command not found: nix-store
error: cannot connect to '$USER@$HOST'
```
The way MacOS populates the `PATH` environment differs from other environments. ([Some background](https://gist.github.com/Linerre/f11ad4a6a934dcf01ee8415c9457e7b2))
There are two possible workarounds for this:
* **(Preferred)** Update the remote builder URL to include the `remote-program` parameter pointing to `nix-store`. For example:
```bash
nix store ping --store "ssh://$USER@$HOST?remote-program=/nix/var/nix/profiles/default/bin/nix-store"
```
If you are unsure where the `nix-store` binary is located, run `which nix-store` on the remote.
* Update `/etc/zshenv` on the remote so that `zsh` populates the Nix path for every shell, even those that are neither *interactive* or *login*:
```bash
# Nix
if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
. '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
fi
# End Nix
```
<details>
<summary>This strategy has some behavioral caveats, namely, <code>$PATH</code> may have unexpected contents</summary>
For example, if `$PATH` gets unset then a script invoked, `$PATH` may not be as empty as expected:
```bash
$ cat example.sh
#! /bin/zsh
echo $PATH
$ PATH= ./example.sh
/Users/ephemeraladmin/.nix-profile/bin:/nix/var/nix/profiles/default/bin:
```
This strategy results in Nix's paths being present on `$PATH` twice and may have a minor impact on performance.
</details>
## Building a binary
Since you'll be using `nix-installer` to install Nix on systems without Nix, the default build is a static binary.
@ -298,7 +329,7 @@ nix build -L "github:determinatesystems/nix-installer/$NIX_INSTALLER_TAG#nix-ins
Then copy the `result/bin/nix-installer` to the machine you wish to run it on.
You can also add `nix-installer` to a system without Nix via `cargo`:
You can also add `nix-installer` to a system without Nix via `cargo`, there are no system dependencies to worry about:
```bash
# to build and run a local copy
@ -321,7 +352,7 @@ To make this build portable, pass ` --target x86_64-unknown-linux-musl`.
## As a library
> **Warning**
> Use as a library is still experimental, if you're using this, please let us know and we can make a path to stablization.
> Use as a library is still experimental. This feature is likely to be removed in the future without an advocate. If you're using this, please let us know and we can make a path to stablization.
Add `nix-installer` to your dependencies:
@ -372,52 +403,40 @@ curl -sSf -L https://github.com/DeterminateSystems/nix-installer/releases/downlo
./nix-installer install
```
## Quirks
While `nix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
## Installation Differences
### Using MacOS remote SSH builders, Nix binaries are not on `$PATH`
Differing from the upstream [Nix](https://github.com/NixOS/nix) installer scripts:
When connecting to a Mac remote SSH builder users may sometimes see this error:
* In `nix.conf`:
+ the `auto-allocate-uids`, `nix-command` and `flakes` features are enabled
+ `bash-prompt-prefix` is set
+ `auto-optimise-store` is set to `true` (On Linux only)
* `extra-nix-path` is set to `nixpkgs=flake:nixpkgs`
* `auto-allocate-uids` is set to `true`. (On Linux only)
* an installation receipt (for uninstalling) is stored at `/nix/receipt.json` as well as a copy of the install binary at `/nix/nix-installer`
* `nix-channel --update` is not run, `~/.nix-channels` is not provisioned
* `NIX_SSL_CERT_FILE` is set in the various shell profiles if the `ssl-cert-file` argument is used.
```bash
$ nix store ping --store "ssh://$USER@$HOST"
Store URL: ssh://$USER@$HOST
zsh:1: command not found: nix-store
error: cannot connect to '$USER@$HOST'
```
## Motivations
The way MacOS populates the `PATH` environment differs from other environments. ([Some background](https://gist.github.com/Linerre/f11ad4a6a934dcf01ee8415c9457e7b2))
The existing upstream scripts do a good job, however they are difficult to maintain.
There are two possible workarounds for this:
Subtle differences in the shell implementations and tool used in the scripts make it difficult to make meaningful changes to the installer.
* **(Preferred)** Update the remote builder URL to include the `remote-program` parameter pointing to `nix-store`. For example:
```bash
nix store ping --store "ssh://$USER@$HOST?remote-program=/nix/var/nix/profiles/default/bin/nix-store"
```
If you are unsure where the `nix-store` binary is located, run `which nix-store` on the remote.
* Update `/etc/zshenv` on the remote so that `zsh` populates the Nix path for every shell, even those that are neither *interactive* or *login*:
```bash
# Nix
if [ -e '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh' ]; then
. '/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh'
fi
# End Nix
```
<details>
<summary>This strategy has some behavioral caveats, namely, <code>$PATH</code> may have unexpected contents</summary>
The Determinate Nix installer has numerous advantages:
For example, if `$PATH` gets unset then a script invoked, `$PATH` may not be as empty as expected:
```bash
$ cat example.sh
#! /bin/zsh
echo $PATH
$ PATH= ./example.sh
/Users/ephemeraladmin/.nix-profile/bin:/nix/var/nix/profiles/default/bin:
```
This strategy results in Nix's paths being present on `$PATH` twice and may have a minor impact on performance.
* keeping an installation receipt for easy uninstallation
* offering users a chance to review an accurate, calculated install plan
* having 'planners' which can create appropriate install plans for complicated targets
* offering users with a failing install the chance to do a best-effort revert
* improving performance by maximizing parallel operations
* supporting a expanded test suite including 'curing' cases
* supporting SELinux and OSTree based distributions without asking users to make compromises
* operating as a single, static binary with external dependencies such as `openssl`, only calling existing system tools (like `useradd`) where necessary
It has been wonderful to collaborate with other participants in the Nix Installer Working Group and members of the broader community. The working group maintains a [foundation owned fork of the installer](https://github.com/nixos/experimental-nix-installer/).
</details>
## Diagnostics
@ -447,3 +466,5 @@ You can read the full privacy policy for [Determinate Systems][detsys], the crea
[diagnosticdata]: https://github.com/DeterminateSystems/nix-installer/blob/f9f927840d532b71f41670382a30cfcbea2d8a35/src/diagnostics.rs#L29-L43
[privacy]: https://determinate.systems/privacy
[systemd]: https://systemd.io
[wslg]: https://github.com/microsoft/wslg
[nixgl]: https://github.com/guibou/nixGL