Documentation on readthedocs is incompelete

[dschrempf]

The documentation for NixOps latest is incomplete, see [1]. It misses great parts that are available in the documentation for NixOps 1.5 and NixOps 1.7 [2,3]. I was not able to understand how NixOps works from the latest manual, however, it is the first link presented by Google. The manual for NixOps Version 1.8pre3071_2b63a9a [4] can be found via Google, but it also misses a lot of information still available in the manual for NixOps 1.7.

Please correct me, if my statements are wrong! I just wanted to express that it is really hard to find valid resources for learning NixOps. On the other hand, if NixOps is superseded by other tools, it should probably be stated somewhere.

Thank you!

References:
[1] https://nixops.readthedocs.io/en/latest/introduction.html
[2] https://releases.nixos.org/nixops/nixops-1.7/manual/manual.html (which is basically not shown on Google)
[3] https://releases.nixos.org/nixops/nixops-1.5/manual/manual.html
[4] https://hydra.nixos.org/build/115931128/download/1/manual/manual.html (is there a better link available?)

[yajo]

Thank you for this issue. I was becoming crazy trying to get my hands on NixOps. Now I'll become crazy, but with docs 😆

Just to add a specific use case for those docs, since I didn't find them, I just went and added the flake input and tried to infer what this expects by reading the error messages. However I got to this one:

> nixops list

WARNING: NixOps 1.0 -> 2.0 conversion step required

NixOps 2.0 added support for multiple storage backends.

Upgrade steps:
1. Open /var/home/yajo/prodevel/moduground
2. Add:
    network.storage.legacy = {
      databasefile = "~/.nixops/deployments.nixops";
    };
3. Rerun

See https://nixops.readthedocs.io/en/latest/manual/migrating.html#state-location for more guidance.

So I went ahead and visited that link. It turns out it expects me to know what is the state, what it was (legacy) and what plugins are available so I can choose where to store it. But I know none of those things. And the docs don't explain. It's really a bad onboarding experience, I hope it can be improved.

I'll go read the 1.7 docs and see if it lets me understand more 😄

[mnakama]

Yeah, I'm having the same problem. Following https://nixops.readthedocs.io/en/latest/overview.html and using nixopsUnstable (because it seems that's the one I'm supposed to use?)

1. I create the trivial-nixos.nix file in my home directory, substituting a real nixos system's IP for "1.2.3.4".

{
  my-nix-host =
    { config, pkgs, ... }:
    {
      deployment.targetHost = "10.10.10.10";
    };
}

2. According to the next section, "Accessing machines", I should be able to ssh into it like this:

% nixops ssh my-nix-host
Traceback (most recent call last):
  File "/nix/store/2cx1fs4szna40w0az4s1nvvqnskkkazg-python3.10-nixops-2.0.0-pre-683baa6/bin/.nixops-wrapped", line 9, in <module>
    sys.exit(main())
  File "/nix/store/hlafx43k4jawd717v2aqjckwp4j1cwgb-python3-3.10.11-env/lib/python3.10/site-packages/nixops/__main__.py", line 56, in main
    args.op(args)
  File "/nix/store/hlafx43k4jawd717v2aqjckwp4j1cwgb-python3-3.10.11-env/lib/python3.10/site-packages/nixops/script_defs.py", line 938, in op_ssh
    with network_state(
  File "/nix/store/rpri9nb8xpwwqakyrqbg8zdslkjs2hd3-python3-3.10.11/lib/python3.10/contextlib.py", line 135, in __enter__
    return next(self.gen)
  File "/nix/store/hlafx43k4jawd717v2aqjckwp4j1cwgb-python3-3.10.11-env/lib/python3.10/site-packages/nixops/script_defs.py", line 102, in network_state
    network = eval_network(get_network_file(args))
  File "/nix/store/hlafx43k4jawd717v2aqjckwp4j1cwgb-python3-3.10.11-env/lib/python3.10/site-packages/nixops/script_defs.py", line 60, in get_network_file
    raise ValueError(f"Neither flake.nix nor nixops.nix exists in {network_dir}")
ValueError: Neither flake.nix nor nixops.nix exists in /home/matt

ok, so I reason that maybe I need to rename trivial-nixos.nix to nixops.nix:

% mv trivial-nixos.nix nixops.nix
% nixops ssh my-nix-host
error: attribute 'network' missing

       at /nix/store/hlafx43k4jawd717v2aqjckwp4j1cwgb-python3-3.10.11-env/lib/python3.10/site-packages/nix/eval-machine-info.nix:53:26:

           52|       else throw "NixOps network must have a 'nixpkgs' attribute"
           53|     else (builtins.head (network.network)).nixpkgs or (import <nixpkgs> { inherit system; });
             |                          ^
           54|
error: evaluation of the deployment specification failed

Uhh... so I'm missing something, maybe? Searching the web, I find that maybe I need to do nixops create first?

% nixops create ./nixops.nix
usage: nixops [-h] [--version] [--pdb] operation ...
nixops: error: unrecognized arguments: ./nixops.nix

Then I gave up and searched the github issues... The README.md points me to a manual that has the wrong steps. readthedocs has another manual that has the wrong steps. Where are the docs that say how to actually start using this? It looks like this hasn't had documentation since 2021? I wouldn't mind writing the docs, but I can't even get off the ground.

[akavel]

FWIW, this very week I experimented a bit with NixOps ("2.0", with flakes), and achieved some success. I'm trying to document it in a writeup article (intended to hopefully become available on a blog I hope to eventually set up — with NixOps nonetheless). It's in a somewhat unpolished/draft state as of yet, but I think it might still be useful to you & others even as-is¹, so if you're interested, the current WIP is available at:

akavel/scribbles: /_drafts/nixops-howto.md

Footnotes

1. given both the current state of NixOps docs, and also a degree of perfectionism in me resulting in my rarely feeling like any article I wrote is polished enough to be publishable... :/ ↩