Skip to content

docs: promote substituter and simplify flake examples #432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jfroche wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: promote substituter and simplify flake examples #432

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,6 @@ There is currently no release plan that follows nixpkgs releases, but ad-hoc rel
owner = "numtide";
repo = "system-manager";
ref = "release-24.05";
inputs.nixpkgs.follows = "nixpkgs";
};
};
}
Expand Down
186 changes: 29 additions & 157 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,206 +11,78 @@ Using NixOS-style declarative configurations, you describe what your system shou

You don't need to be an expert in Nix to use it, as its syntax is straightforward. But if you're familiar with Nix and Home Manager, think of System Manager as being similar, but for your entire machine. Whereas Home Manager manages user environments, System Manager manages the entire system, starting at root-level configurations, packages, and services, using the same reliable, Nix-based model.

System Manager builds on the many modules that already exist in [NixOS].

# Full Documentation
System Manager builds on the many modules that already exist in [NixOS](https://nixos.org/).

You can find the [full documentation here](https://system-manager.net/main/).

## Quick Example to Get Started
## Quick example

We will assume you're using a non-NixOS distribution (such as Ubuntu) and you have Nix already installed, with flakes enabled.
We assume you're using a non-NixOS distribution (such as Ubuntu) and you have [Nix installed](https://system-manager.net/main/how-to/install/) with flakes enabled.

System Manager has an "init" subcommand that can build a set of starting files for you. By default, it places the files in `~/.config/system-manager`. You can run this init subcommand by typing:
Run the init subcommand to generate a starting configuration in `~/.config/system-manager`:

```
nix run 'github:numtide/system-manager' -- init
```

If you see an error regarding experimental nix features, instead type the following:

```
nix run 'github:numtide/system-manager' --extra-experimental-features 'nix-command flakes' -- init
```

> [!Tip]
> If you still have problems running this step, check out our full [Getting Started Guide](https://system-manager.net/main/tutorials/getting-started/), which includes how to handle issues of running as root, and whether you've installed Nix to be used by a single user.

> [!Note]
> You can optionally run the above under `sudo`, which will place the files under `/root/.config/system-manager`. You might need to pass the path, depending on how you installed Nix:
> `sudo env PATH="$PATH" nix run 'github:numtide/system-manager' -- init`

You will now have two files under `~/.config/system-manager` (or `/root/.config/system-manager` if you ran the above under sudo):

- flake.nix
- system.nix

Go ahead and switch to the folder:

```
cd ~/.config/system-manager
```

(Or to the root equivalent.)
> [!Tip]
> If you have problems running this step, check out our full [Getting Started Guide](https://system-manager.net/main/tutorials/getting-started/).

Here is what `flake.nix` looks like. (Note: If you enabled experimental features from the command line rather than through `/etc/nix/nix.conf`, this file might not exist; you can create it manually and copy the following into it.)
This creates two files: `flake.nix` and `system.nix`. Here is what `flake.nix` looks like:

```nix
{
description = "Standalone System Manager configuration";

nixConfig = {
extra-substituters = [ "https://cache.numtide.com" ];
extra-trusted-public-keys = [ "niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=" ];
};

inputs = {
# Specify the source of System Manager and Nixpkgs.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
system-manager = {
url = "github:numtide/system-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
system-manager.url = "github:numtide/system-manager";
};

outputs =
{
self,
nixpkgs,
system-manager,
...
}:
{ system-manager, ... }:
{
systemConfigs.default = system-manager.lib.makeSystemConfig {
# Specify your system configuration modules here, for example,
# the path to your system.nix.
modules = [ ./system.nix ];

# Optionally specify extraSpecialArgs and overlays
};
};
}
```

For these examples, we won't use the `system.nix` file; we'll create separate configuration files for each example.

Find the following line in `flake.nix`:

```
modules = [ ./system.nix ];
```

and change it to this:

```
modules = [ ./cli_tools.nix ];
```

Create a file in the same folder called `cli_tools.nix` and add the following into it:

```nix
{ pkgs, ... }:
{
config = {
nixpkgs.hostPlatform = "x86_64-linux";

environment.systemPackages = with pkgs; [
btop # Beautiful system monitor
bat # Modern 'cat' with syntax highlighting
];
};
}
Open `system.nix` and add packages to the `systemPackages` list:

```diff
systemPackages = with pkgs; [
- # hello
+ btop
+ bat
];
```

This specifies a configuration that includes `btop` and `bat` to be installed on the system. To do so, execute System Manager using the nix command (assuming you have experimental features nix-command and flakes turned on):
Then apply the configuration:

```
cd ~/.config/system-manager
nix run 'github:numtide/system-manager' -- switch --sudo
```

Also, note that you might need to enable `nix-commands` and `flakes` if you don't already have them set in `/etc/nix/nix.conf`:

```
nix --extra-experimental-features 'nix-command flakes' run 'github:numtide/system-manager' -- switch --sudo
```
> [!Tip]
> The first time you run this, Nix will ask whether to trust the Numtide cache substituter. Answer yes — it provides pre-built binaries so you don't have to build everything from source.

> [!Note]
> The first time you run System Manager, it will update your path by adding an entry in the /etc/profile.d folder. For this change to take effect, you need to log out and then log back in. However, if you don't want to log out, you can source the file:
> The first time you run System Manager, it adds an entry in `/etc/profile.d/` to update your `$PATH`. Log out and back in for it to take effect, or run:
> `source /etc/profile.d/system-manager-path.sh`

And now the two commands `btop` and `bat` should be available on your system:

```
$ btop --version
btop version: 1.4.5
Compiled with: g++ (14.3.0)
Configured with: cmake -DBTOP_STATIC=OFF -DBTOP_GPU=ON
$ bat --version
bat 0.26.0
```

Want to remove a package? Simply remove it or comment it out in the `cli_tools.nix` file, and run it again. For example, if you want to remove `bat`, simply update the `default.nix` to the following:

```nix
{ pkgs, ... }:
{
nixpkgs.hostPlatform = "x86_64-linux";

environment.systemPackages = with pkgs; [
btop # Beautiful system monitor
# bat # Comment out or remove
];
}
```

## Regarding the Error

You might notice an error that looks like this:

`[2025-11-17T15:06:46Z ERROR system_manager::activate::etc_files] Error while trying to link directory /etc/.system-manager-static/nix: Unmanaged path already exists in filesystem, please remove it and run system-manager again: /etc/nix/nix.conf`

You can safely ignore it; or, you can allow System Manager to take control of `nix.conf`. If you choose to have System Manager take control of `nix.conf`, rename `nix.conf` to a backup name, such as `nix_conf_backup`, and run System Manager again. Note, however, that if you had settings in your `nix.conf` file, they might not appear in the new file System Manager generates. For that read the following section, [Adding in Experimental Features](#adding-in-experimental-features).

## Adding in Experimental Features

It's possible that you had a `nix.conf` file in `/etc/nix` that had experimental features set. And if you allowed System Manager to take control of that file, your setting will likely be gone. But that's okay; you now have control of your system right from the `flake.nix` file. You can add experimental features inside the modules list like so:

```nix
{
description = "Standalone System Manager configuration";

inputs = {
# Specify the source of System Manager and Nixpkgs.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
system-manager = {
url = "github:numtide/system-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
};

outputs =
{
self,
nixpkgs,
system-manager,
...
}:
{
systemConfigs.default = system-manager.lib.makeSystemConfig {
# Specify your system configuration modules here, for example,
# the path to your system.nix.

modules = [
# Place additional settings here:
{
nix.settings.experimental-features = "nix-command flakes";
}
./cli_tools.nix
];

# Optionally specify extraSpecialArgs and overlays
};
};
}
```

Then re-run System Manager and your changes will take effect; now you should have the two experimental features set, `nix-command` and `flakes`.
The two commands `btop` and `bat` should now be available on your system.
Want to remove a package? Simply remove it or comment it out in `system.nix` and run the command again.

## Supported Systems

Expand All @@ -230,7 +102,7 @@ System Manager is currently only supported on NixOS and Ubuntu. However, it can
## Supported Nix

Nix should be installed with the [nix-installer](https://github.com/NixOS/nix-installer).
System manager is tested against Nix 2.32 and above installed via nix-installer.
System manager is tested against Nix 2.33.0 and above installed via nix-installer.

## Commercial support

Expand Down
4 changes: 2 additions & 2 deletions crates/system-manager/src/main.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ use system_manager_engine::{NixOptions, StorePath, PROFILE_DIR};

/// The bytes for the NixOS flake template is included in the binary to avoid unnecessary
/// network calls when initializing a system-manager configuration from the command line.
pub const NIXOS_FLAKE_TEMPLATE: &[u8; 808] = include_bytes!("../../../templates/nixos/flake.nix");
pub const NIXOS_FLAKE_TEMPLATE: &[u8; 681] = include_bytes!("../../../templates/nixos/flake.nix");

/// The bytes for the standalone flake template is included in the binary to avoid unnecessary
/// network calls when initializing a system-manager configuration from the command line.
pub const STANDALONE_FLAKE_TEMPLATE: &[u8; 864] =
pub const STANDALONE_FLAKE_TEMPLATE: &[u8; 492] =
include_bytes!("../../../templates/standalone/flake.nix");

/// The bytes for the standalone module template is included in the binary to avoid unnecessary
Expand Down
51 changes: 17 additions & 34 deletions docs/site/examples/custom-app.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,44 +62,27 @@ First we have a flake much like the usual starting point:
{
description = "Standalone System Manager configuration";

nixConfig = {
extra-substituters = [ "https://cache.numtide.com" ];
extra-trusted-public-keys = [ "niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=" ];
};

inputs = {
# Specify the source of System Manager and Nixpkgs.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
system-manager = {
url = "github:numtide/system-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
system-manager.url = "github:numtide/system-manager";
};

outputs =
{
self,
nixpkgs,
system-manager,
...
}:
let
system = "x86_64-linux";
in
{
systemConfigs.default = system-manager.lib.makeSystemConfig {

# Specify your system configuration modules here, for example,
# the path to your system.nix.
modules = [

{
nix.settings.experimental-features = "nix-command flakes";
services.myapp.enable = true;
}
./system.nix
./nginx.nix
./bun-app.nix
];

# Optionally specify extraSpecialArgs and overlays
};
outputs = { system-manager, ... }: {
systemConfigs.default = system-manager.lib.makeSystemConfig {
modules = [
{
services.myapp.enable = true;
}
./system.nix
./nginx.nix
./bun-app.nix
];
};
};
}
```

Expand Down
13 changes: 7 additions & 6 deletions docs/site/examples/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,16 @@ This example shows how to install Docker and configure it as a systemd service.
{
description = "System Manager - Docker Example";

nixConfig = {
extra-substituters = [ "https://cache.numtide.com" ];
extra-trusted-public-keys = [ "niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=" ];
};

inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
system-manager = {
url = "github:numtide/system-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
system-manager.url = "github:numtide/system-manager";
};

outputs = { self, nixpkgs, system-manager }: {
outputs = { system-manager, ... }: {
systemConfigs.default = system-manager.lib.makeSystemConfig {
modules = [
{
Expand Down
34 changes: 10 additions & 24 deletions docs/site/examples/timer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,20 @@ This example demonstrates how to install a systemd timer that runs every minute.
{
description = "Standalone System Manager configuration";

nixConfig = {
extra-substituters = [ "https://cache.numtide.com" ];
extra-trusted-public-keys = [ "niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=" ];
};

inputs = {
# Specify the source of System Manager and Nixpkgs.
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
system-manager = {
url = "github:numtide/system-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
system-manager.url = "github:numtide/system-manager";
};

outputs =
{
self,
nixpkgs,
system-manager,
...
}:
let
system = "x86_64-linux";
in
{
systemConfigs.default = system-manager.lib.makeSystemConfig {
# Specify your system configuration modules here, for example,
# the path to your system.nix.
modules = [ ./system.nix ];

# Optionally specify extraSpecialArgs and overlays
};
outputs = { system-manager, ... }: {
systemConfigs.default = system-manager.lib.makeSystemConfig {
modules = [ ./system.nix ];
};
};
}
```

Expand Down
Loading