nixos-config/docs/content/en-US/lay-of-the-land/project-structure/index.adoc

---

title: Project structure --- = Project structure

Last and foremost, we have the project directory — the environment you’ll be living in for the next year, tinkering your Nix configs. . It is required to be familiar with the workspace, after all. My configuration takes a lot of cues from devos (which is unfortunately is a lot to take if you’re just beginning to grok Nix as a whole).

My NixOS config should look like the following:

nixos-config
├── hosts/
├── lib/
├── modules/
├── pkgs/
├── scripts/
├── secrets/
├── shells/
├── templates/
├── users/
├── default.nix
├── flake.lock
├── flake.nix
├── images.toml
└── README.adoc

One of the more notable files here when first start looking is the ./images.toml file where it contains a description of the images. For more details, see [declarative-host-management].

Most of the said folders are related to a flake output attribute, see [whats-in-my-flake] for more details.

• ./hosts/ contain machine-specific configuration. This usually configures like the hardware setup, timezone, and users. Host configurations are also exported in the flakes in outputs.nixosConfigurations.

• ./modules/ contain my custom modules including NixOS and home-manager modules. For more information, see the related documentation.

• ./pkgs/ contains my custom packages. It is exported in the flakes at outputs.packages compiled through various systems.

• ./scripts/ contains various scripts for various purposes. Should be self-explanatory.

• ./secrets/ contains my cluster-wide secrets managed with sops and sops-nix. Take note, each component (e.g., hosts, modules, users) could have their own specific secrets.

• ./shells/ contains my development shells for interacting with the usual type of projects. Setting this up can bring benefits outside of NixOS (unless you’re interacting with projects with any OpenGL-related stuff). ^[1]

• ./templates/ contains my custom templates handy for quickly initializing for various types of projects.

• ./users/ contains my home-manager configurations. It is exported in the flakes at outputs.homeConfigurations. For more information, see the related documentation.

---

1. Since packages brought from Nix shells can only work with the store, a container might be better at some situations.