forked from lix-project/lix-installer
Readme cutificiation (#618)
* Engage README cutification subroutine * Trimming
This commit is contained in:
Ana Hobden
GitHub
parent
8395b40223
commit
d7412ba096
185
README.md
185
README.md
|
|
@ -1,18 +1,16 @@
|
|||
# Install Nix with flakes using the Determinate Nix Installer
|
||||
|
||||
_🎉 Celebrating over 500,000 successful installations! 🎉_
|
||||
# The Determinate Nix Installer
|
||||
|
||||
[](https://crates.io/crates/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
|
||||
Loading…
Reference in a new issue