lix-installer/README.md
2024-04-12 06:33:04 -06:00

359 lines
11 KiB
Markdown

# The Lix Installer
A fast, friendly, and reliable tool to help you use Lix, the community implementation of the nix tooling.
Based on the [Determinate Installer](https://install.determinate.systems).
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install
```
## Usage
Install Nix with the default planner and options:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install
```
Or, to download a platform specific Installer binary yourself:
```bash
$ curl -sL -o lix-installer https://install.lix.systems/lix/lix-installer-x86_64-linux
$ chmod +x lix-installer
$ ./lix-installer
```
`lix-installer` installs Lix by following a *plan* made by a *planner*. Review the available planners:
```bash
$ ./lix-installer install --help
Execute an install (possibly using an existing plan)
To pass custom options, select a planner, for example `lix-installer install linux-multi --help`
Usage: lix-installer install [OPTIONS] [PLAN]
lix-installer install <COMMAND>
Commands:
linux
A planner for Linux installs
steam-deck
A planner suitable for the Valve Steam Deck running SteamOS
help
Print this message or the help of the given subcommand(s)
# ...
```
Planners have their own options and defaults, sharing most of them in common:
```bash
$ ./lix-installer install linux --help
A planner for Linux installs
Usage: lix-installer install linux [OPTIONS]
Options:
# ...
--nix-build-group-name <NIX_BUILD_GROUP_NAME>
The Nix build group name
[env: NIX_INSTALLER_NIX_BUILD_GROUP_NAME=]
[default: nixbld]
--nix-build-group-id <NIX_BUILD_GROUP_ID>
The Nix build group GID
[env: NIX_INSTALLER_NIX_BUILD_GROUP_ID=]
[default: 3000]
# ...
```
Planners can be configured via environment variable or command arguments:
```bash
$ curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | NIX_BUILD_GROUP_NAME=nixbuilder sh -s -- install linux-multi --nix-build-group-id 4000
# Or...
$ NIX_BUILD_GROUP_NAME=nixbuilder ./lix-installer install linux-multi --nix-build-group-id 4000
```
### Upgrading Lix
You can upgrade Lix with:
```
sudo -i nix upgrade-nix
```
Alternatively, you can [uninstall](#uninstalling) and [reinstall](#usage) with a different version of the `lix-installer`.
### Uninstalling
You can remove a `lix-installer`-installed Nix by running
```bash
/nix/lix-installer uninstall
```
### Without systemd (Linux only)
> **Warning**
> When `--init none` is used, _only_ `root` or users who can elevate to `root` privileges can run Lix's nix command:
>
> ```bash
> sudo -i nix run nixpkgs#hello
> ```
If you don't use [systemd], you can still install Nix by explicitly specifying the `linux` plan and `--init none`:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install linux --init none
```
### In a container
In Docker/Podman containers or WSL2 instances where an init (like `systemd`) is not present, pass `--init none`.
For containers (without an init):
> **Warning**
> When `--init none` is used, _only_ `root` or users who can elevate to `root` privileges can run Lix's nix command:
>
> ```bash
> sudo -i nix run nixpkgs#hello
> ```
```dockerfile
# Dockerfile
FROM ubuntu:latest
RUN apt update -y
RUN apt install curl -y
RUN curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install linux \
--extra-conf "sandbox = false" \
--init none \
--no-confirm
ENV PATH="${PATH}:/nix/var/nix/profiles/default/bin"
RUN nix run nixpkgs#hello
```
```bash
docker build -t ubuntu-with-nix .
docker run --rm -ti ubuntu-with-nix
docker rmi ubuntu-with-nix
# or
podman build -t ubuntu-with-nix .
podman run --rm -ti ubuntu-with-nix
podman rmi ubuntu-with-nix
```
For containers with a systemd init:
```dockerfile
# Dockerfile
FROM ubuntu:latest
RUN apt update -y
RUN apt install curl systemd -y
RUN curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install linux \
--extra-conf "sandbox = false" \
--no-start-daemon \
--no-confirm
ENV PATH="${PATH}:/nix/var/nix/profiles/default/bin"
RUN nix run nixpkgs#hello
CMD [ "/bin/systemd" ]
```
```bash
podman build -t ubuntu-systemd-with-nix .
IMAGE=$(podman create ubuntu-systemd-with-nix)
CONTAINER=$(podman start $IMAGE)
podman exec -ti $CONTAINER /bin/bash
podman rm -f $CONTAINER
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
We **strongly recommend** [enabling systemd](https://ubuntu.com/blog/ubuntu-wsl-enable-systemd), then installing Lix as normal:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install
```
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 systemd 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 Lix's nix commands:
>
> ```bash
> sudo -i nix run nixpkgs#hello
> ```
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install linux --init none
```
### Skip confirmation
If you'd like to bypass the confirmation step, you can apply the `--no-confirm` flag:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install --no-confirm
```
This is especially useful when using the installer in non-interactive scripts.
## Quirks
While `lix-installer` tries to provide a comprehensive and unquirky experience, there are unfortunately some issues which may require manual intervention or operator choices.
### Using MacOS after removing `nix` while `nix-darwin` was still installed, network requests fail
If any variant of `nix` was previously uninstalled without uninstalling `nix-darwin` first, users may experience errors similar to this:
```bash
$ nix shell nixpkgs#curl
error: unable to download 'https://cache.nixos.org/g8bqlgmpa4yg601w561qy2n576i6g0vh.narinfo': Problem with the SSL CA cert (path? access rights?) (77)
```
This occurs because `nix-darwin` provisions an `org.nixos.activate-system` service which remains after Nix is uninstalled.
The `org.nixos.activate-system` service in this state interacts with the newly installed Nix and changes the SSL certificates it uses to be a broken symlink.
```bash
$ ls -lah /etc/ssl/certs
total 0
drwxr-xr-x 3 root wheel 96B Oct 17 08:26 .
drwxr-xr-x 6 root wheel 192B Sep 16 06:28 ..
lrwxr-xr-x 1 root wheel 41B Oct 17 08:26 ca-certificates.crt -> /etc/static/ssl/certs/ca-certificates.crt
```
The problem is compounded by the matter that the [`nix-darwin` uninstaller](https://github.com/LnL7/nix-darwin#uninstalling) will not work after uninstalling Nix, since it uses Nix and requires network connectivity.
It's possible to resolve this situation by removing the `org.nixos.activate-system` service and the `ca-certificates`:
```bash
$ sudo rm /Library/LaunchDaemons/org.nixos.activate-system.plist
$ sudo launchctl bootout system/org.nixos.activate-system
$ /nix/lix-installer uninstall
$ sudo rm /etc/ssl/certs/ca-certificates.crt
```
Then run the `lix-installer` again, and it should work.
Up-to-date versions of the `lix-installer` will refuse to uninstall until `nix-darwin` is uninstalled first, helping mitigate this problem.
## Building a binary
Since you'll be using `lix-installer` to install Nix on systems without Nix, the default build is a static binary.
Build a portable Linux binary on a system with Nix:
```bash
# to build a local copy
nix build -L ".#lix-installer-static"
```
On Mac:
```bash
# to build a local copy
nix build -L ".#lix-installer"
```
Then copy the `result/bin/lix-installer` to the machine you wish to run it on.
You can also add `lix-installer` to a system without Lix via `cargo`. There are no system dependencies to worry about:
```bash
# to build and run a local copy
RUSTFLAGS="--cfg tokio_unstable" cargo run -- --help
# to build the remote main development branch
RUSTFLAGS="--cfg tokio_unstable" cargo install --git https://git.lix.systems/lix-project/lix-installer
lix-installer --help
# for a specific version of the installer:
export NIX_INSTALLER_TAG="v0.6.0"
RUSTFLAGS="--cfg tokio_unstable" cargo install --git https://git.lix.systems/lix-project/lix-installer --tag $NIX_INSTALLER_TAG
lix-installer --help
```
To make this build portable, pass ` --target x86_64-unknown-linux-musl`.
> **Note**
> We currently require `--cfg tokio_unstable` as we utilize [Tokio's process groups](https://docs.rs/tokio/1.24.1/tokio/process/struct.Command.html#method.process_group), which wrap stable `std` APIs, but are unstable due to it requiring an MSRV bump.
## As a library
> **Warning**
> 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 stabilization.
Add `lix-installer` to your dependencies:
```bash
cargo add lix-installer
```
If you are **building a CLI**, check out the `cli` feature flag for `clap` integration.
You'll also need to edit your `.cargo/config.toml` to use `tokio_unstable` as we utilize [Tokio's process groups](https://docs.rs/tokio/1.24.1/tokio/process/struct.Command.html#method.process_group), which wrap stable `std` APIs, but are unstable due to it requiring an MSRV bump:
```toml
# .cargo/config.toml
[build]
rustflags=["--cfg", "tokio_unstable"]
```
Then it's possible to review the [documentation](https://docs.rs/lix-installer/latest/lix_installer/):
```bash
cargo doc --open -p lix-installer
```
## Accessing other versions
Each installer version has an [associated supported nix version](src/settings.rs) -- if you pin the installer version, you'll also indirectly pin to the associated nix version.
You can also override the `nix` version via `--nix-package-url` or `NIX_INSTALLER_NIX_PACKAGE_URL=` but doing so is not recommended since we haven't tested that combination.
Here are some example `nix` package URLs including nix version, OS and architecture:
* https://releases.nixos.org/nix/nix-2.18.1/nix-2.18.1-x86_64-linux.tar.xz
* https://releases.nixos.org/nix/nix-2.18.1/nix-2.18.1-aarch64-darwin.tar.xz
## Installation Differences
Differing from the upstream [Nix](https://github.com/NixOS/nix) installer scripts:
* In `nix.conf`:
+ the `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`
* `max-jobs` is set to `auto`
* `upgrade-nix-store-path-url` is set to `https://install.lix.systems/lix-upgrade/stable/universal`
* an installation receipt (for uninstalling) is stored at `/nix/receipt.json` as well as a copy of the install binary at `/nix/lix-installer`
* `nix-channel --update` is not run, `~/.nix-channels` is not provisioned
* `ssl-cert-file` is set in `/etc/nix/nix.conf` if the `ssl-cert-file` argument is used.
## No Telemetry Included
The Lix installer respects user privacy, and thus collects no information.