jeff docs #287

zimbatm · 2025-11-24T18:16:31Z

Ready for high-level review

zimbatm · 2025-12-22T13:34:26Z

documentation/docs/getting-started.md

+Then answer yes to the four questions.
+
+[TODO: I'll explore the four questions further and write a short paragraph about them]


What questions?

[2025-12-22T13:33:40Z INFO system_manager] Initializing new system-manager configuration at '/home/zimbatm/.config/system-manager' [2025-12-22T13:33:40Z INFO system_manager] 1153B written to '/home/zimbatm/.config/system-manager/system.nix' [2025-12-22T13:33:40Z INFO system_manager] 739B written to '/home/zimbatm/.config/system-manager/flake.nix' [2025-12-22T13:33:40Z INFO system_manager] Configuration '/home/zimbatm/.config/system-manager' ready for activation!

These questions come up when you're working on a clean system. I'm adding them to the text right now:

Do you want to allow configuration setting 'extra-substituters' to be set to 'https://cache.numtide.com' (y/N)?

Do you want to permanently mark this value as trusted (y/N)?

Do you want to allow configuration setting 'extra-trusted-public-keys' to be set to 'niks3.numtide.com-1:DTx8wZduET09hRmMtKdQDxNNthLQETkc/yaX7M4qK0g=' (y/N)?

Do you want to permanently mark this value as trusted (y/N)?

zimbatm · 2025-12-22T13:34:58Z

documentation/docs/getting-started.md

+
+This will fully demonstrate the declarative nature of these configuration files.
+
+First, in the ~/.config/system-manager folder, create a file capps apps.nix and place the following in it:


zimbatm · 2025-12-22T13:36:13Z

documentation/docs/getting-started.md

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


If you use "diff" instead of "nix" as the language, you can present a diff view. That might be a bit cleaner.

Oh! Good call. I'll try that. Thanks!

zimbatm · 2025-12-22T13:36:37Z

documentation/docs/getting-started.md

+
+
+```
+sudo env PATH="$PATH" nix --extra-experimental-features 'nix-command flakes' run 'github:numtide/system-manager' -- switch --flake .


switch to the --sudo flag

zimbatm · 2025-12-22T13:39:01Z

documentation/docs/getting-started.md

 # Getting Started

-If you’ve heard of NixOS, you’ve probably heard that it lets you define your entire system in configuration files and then reproduce that system anywhere with a single command. System Manager brings that same declarative model to any Linux distribution, with no reinstalling, no switching operating systems, and no special prerequisites beyond having Nix installed. Instead of manually installing packages, editing /etc files, or configuring system services by hand, you describe the desired state of your machine in a small set of Nix files. System Manager reads that configuration, applies it safely, and keeps previous versions so you can roll back at any time. This guide introduces those ideas step by step, helping you gain the benefits of Nix-style reproducibility and consistency on the Linux system you already have.
+If you’ve heard of NixOS, you’ve probably heard that it lets you define your entire system in configuration files and then reproduce that system anywhere with a single command. System Manager brings that same declarative model to any Linux distribution, with no reinstalling, no switching operating systems, and no special prerequisites beyond having Nix installed.


Maybe add an asterisk to any Linux distribution to say that it's only Ubuntu for now.

The services interface also only works with Linux distributions based on systemd.

zimbatm · 2025-12-22T13:53:14Z

documentation/docs/getting-started.md


+# Concepts for people new to Nix
+
+[Not sure we want this here, or at all, but it's a start. I think this will help people who are new to Nix. If we don't want it, I'll move it to my own personal website.]


Let's keep it here for now. At some point this will go to a shared website like install-nix.com

zimbatm · 2025-12-22T13:54:18Z

documentation/docs/getting-started.md

+## Thoughts on learning the Nix language

+[coming soon]


Remove this for now

zimbatm · 2025-12-22T13:56:26Z

documentation/docs/reference-guide.md


+# Requirements
+
+[TODO: I realized I wrote this section twice, here and in the getting-started guide. I'll combine them and provide the same in both, since some people might just read one doc or the other.]


How about adding an install.md document for this?

In the getting started, tell the user to start with the installation and then come back.

Good idea! I'll do that.

zimbatm · 2025-12-22T13:58:16Z

documentation/docs/reference-guide.md

+/home/ubuntu/.nix-profile/bin/system-manager
+```
+
+[Might be nice to list some ideas about When would you install locally... I'm not sure, can anyone help?]


There isn't a strong case for this. Either it's a new project and you want to run the nix run ... -- init command, or it's an existing project, and then you want to load the system-manager version the flake input is pointing to (like by loading the devshell).

zimbatm · 2025-12-22T14:02:44Z

documentation/docs/reference-guide.md

+
 # Setting up a folder and file structure

+[TEAM: SHOULD THIS GO HERE OR IN THE GETTING STARTED GUIDE? I DON'T WANT TO WEIGH DOWN THE GETTING STARTED GUIDE TOO MUCH, BUT MAYBE IT STILL BELONGS THERE? --JEFFREY]


How to structure your code is a generic Nix problem, not specific to System Manager.

In the Getting Started doc I think the structure you use is fine for the examples, but we want to point out that we recommend using blueprint to properly structure the code if the project gets any more complicated. Blueprint is an opinionated approach and others are also valid.

The reference doc should talk about the APIs of System Manager.

zimbatm · 2025-12-22T14:43:08Z

documentation/docs/examples.md

+```bash
+# Create the group and user
+sudo groupadd nginx
+sudo useradd -r -s /usr/sbin/nologin -g nginx nginx


Add a note that user management is coming soon. After that this won't be needed anymore.

zimbatm · 2025-12-22T14:43:44Z

documentation/docs/examples.md

+
+- Ensure you have the `nginx` user and group created on your system before activating
+- You may need to adjust file paths based on your distribution
+- The nginx binary location is pinned from nixpkgs to ensure reproducibility


Or the user can import the nginx module from NixOS. This gives them a much richer experience.

Also, I realized I duplicated efforts, with nginx samples in the Reference Guide. So I removed this sample altogether and replaced it with a sample that shows how to create a system timer.

zimbatm · 2025-12-22T14:46:33Z

documentation/docs/examples.md

+# Should output: (nothing or "emacs not found")
+
+# Check if the binary still exists in the nix store
+ls -la /nix/store/*emacs*/bin/emacs 2>/dev/null || echo "Emacs removed from active profile"


This would only fail if the /nix/store was garbage collected.

zimbatm · 2025-12-22T14:49:32Z

documentation/docs/examples.md

+
+### 2. Use Flake Inputs Follows
+
+This ensures consistent nixpkgs versions:


Is that enough of a description to make it clear what "follows" does?

zimbatm · 2025-12-22T14:50:37Z

documentation/docs/examples.md

+
+---
+
+## General Tips and Best Practices


Should this go in a FAQ? All of these seem useful to have around.

zimbatm · 2025-12-22T14:51:33Z

documentation/docs/examples.md

+
+# Check PATH
+echo $PATH
+```


If you just installed system-manager, try logging out and back again into your user session.

zimbatm · 2025-12-22T14:51:50Z

documentation/docs/examples.md

+Ensure you're running system-manager with sudo:
+
+```bash
+sudo nix run 'github:numtide/system-manager' -- switch --flake .


Suggested change

sudo nix run 'github:numtide/system-manager' -- switch --flake .

nix run 'github:numtide/system-manager' -- switch --flake . --sudo

zimbatm · 2025-12-22T14:53:20Z

documentation/docs/index.md

+**System Manager** brings the power of NixOS-style declarative configuration to any Linux system.  
+Describe what your system should look like, packages, services, and settings, all in Nix, then apply it safely and atomically with a single command. Each change is reproducible and rollback-ready, just like NixOS generations but without needing to actually run NixOS.
+
+!!! tip "Think of it as Home Manager for your entire machine"
+    Where Home Manager manages user environments, System Manager manages the full system—root-level configuration, packages, and services—using the same reliable, Nix-based model.
+
+## Quick start
+
+```bash
+...
+```


This seems redundant with the README and the other docs.

Removed WIP note from examples document.

Removed duplicate note about combining sections in documentation.

jeffcogswell added 14 commits May 18, 2025 20:12

First set of README updates -- more coming soon

4783706

wip: documentation

0eebe9d

wip: Updated README.md, still need a good bit of cleaning up.

98c37de

wip: Updated README for initial quick-release

50f3f7f

wip: documentation

e60d6c7

wip: documentation

5c4f871

wip: Documentation updates

974dfad

wip: More documentation

9a0ddd4

wip: documentation

172990e

wip: documentation

71955ac

wip: docs

83814df

wip: docs

eadee10

wip: docs

f4f47ce

wip: docs

c73ac2c

zimbatm commented Dec 22, 2025

View reviewed changes

jeffcogswell added 6 commits December 31, 2025 12:20

fix: first round of documentation fixes, more soon

0fbb519

fix: Updated docs

74ddfb8

Clean up examples document by removing WIP note

3bd1f22

Removed WIP note from examples document.

Remove duplicate note in installation documentation

ecdd484

Removed duplicate note about combining sections in documentation.

Removed extra comments

d720a02

fix: Updated TOC, removed extra comments

9cdf3f1

zimbatm mentioned this pull request Jan 6, 2026

jeff merge #308

Merged

		Then answer yes to the four questions.

		[TODO: I'll explore the four questions further and write a short paragraph about them]


		This will fully demonstrate the declarative nature of these configuration files.

		First, in the ~/.config/system-manager folder, create a file capps apps.nix and place the following in it:



		```
		sudo env PATH="$PATH" nix --extra-experimental-features 'nix-command flakes' run 'github:numtide/system-manager' -- switch --flake .


		# Concepts for people new to Nix

		[Not sure we want this here, or at all, but it's a start. I think this will help people who are new to Nix. If we don't want it, I'll move it to my own personal website.]


		# Requirements

		[TODO: I realized I wrote this section twice, here and in the getting-started guide. I'll combine them and provide the same in both, since some people might just read one doc or the other.]


		# Setting up a folder and file structure

		[TEAM: SHOULD THIS GO HERE OR IN THE GETTING STARTED GUIDE? I DON'T WANT TO WEIGH DOWN THE GETTING STARTED GUIDE TOO MUCH, BUT MAYBE IT STILL BELONGS THERE? --JEFFREY]


		### 2. Use Flake Inputs Follows

		This ensures consistent nixpkgs versions:

	sudo nix run 'github:numtide/system-manager' -- switch --flake .
	nix run 'github:numtide/system-manager' -- switch --flake . --sudo

jeff docs #287

Are you sure you want to change the base?

jeff docs #287

Uh oh!

Conversation

zimbatm commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zimbatm commented Nov 24, 2025 •

edited

Loading