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

---
title: Project structure
---
= Project structure

Next, 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 link:{devos-link}[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:

[source, tree]
----
nixos-config
├── docs/
├── hosts/
├── lib/
├── modules/
├── overlays/
├── pkgs/
├── scripts/
├── secrets/
├── shells/
├── templates/
├── users/
├── default.nix
├── flake.lock
├── flake.nix
├── images.toml
├── users.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 xref:../../03-project-specific-setup/01-declarative-host-management/index.adoc[Declarative host management].

A similar file, `./users.toml`, contains the description for the home-manager users to be exported from this flake.
For more details, see xref:../../03-project-specific-setup/02-declarative-user-management/index.adoc[Declarative user management].

Most of the said folders are related to a flake output attribute, see xref:../03-whats-in-my-flake/index.adoc[What's in my flake?] for more details.

* `./docs/` contain the source code for the website.
Currently, it uses link:https://gohugo.io/[Hugo] for statically generating the website.

* `./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 github:{github-repo}[related documentation, path=./modules/README.adoc, rev=master].

* `./overlays/` contain the overlays for several established packages.
This is typically used exclusively for the project and advised to not use it if you're not foodogsquared.

* `./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 github:mozilla/sops[opts=repo] and github:Mic92/sops-nix[opts=repo].
Take note, each component (e.g., hosts, modules, users) could have their own specific secrets.
For more information, see xref:../../03-project-specific-setup/03-secrets-management/index.adoc[Secrets management].

* `./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).
footnote:[Since packages brought from Nix shells can only work with the store, a container might be better at some situations.]

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

* `./users/` contains my github:nix-community/home-manager[opts=repo] configurations.
It is exported in the flakes at `outputs.homeConfigurations`.
For more information, see the github:{github-repo}[related documentation, path=./users/README.adoc, rev=master].