Contributing

Development Shell

A Nix dev shell is available, providing just, nixd, and the tooling wired up as pre-commit hooks (treefmt with nixfmt and prettier, plus commitizen). To enter the dev shell, run:

nix develop ./dev

An .envrc is also provided, so it is recommended to use direnv to automatically enter the dev shell when you cd into the project directory. See this tutorial.

Adding a new service

The project repository is structure to make addition of new services easy. Here’s how to add a new service:

See https://github.com/cachix/devenv/tree/main/src/modules/services for inspiration.

If you don’t find a new service there, see https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/services.

Create a new file ./nix/services/<service-name>.nix file (see ./nix/services/redis.nix for inspiration)
Add the service to the list in ./nix/services/default.nix.
Create a new test file ./nix/services/<service-name>_test.nix (see ./nix/services/redis_test.nix).
Add the test to ./test/flake.nix.

Run the service

just run <service-name>

Run the tests for the service

The previous command will run the services but not the tests. To run the tests, use:

just test <service-name>

or test all services:

just test-all

Add documentation for the new service

It is important to add documentation along with any new services you are contributing. Create a new file ./doc/<service-name>.md (see Clickhouse for example) and add the service to the list in Supported services.

A service that belongs under another one (e.g. a Grafana component) declares its parent

with a reverse folgezettel link — #[[grafana]] — in its own page, and is nested under [[grafana]] in Supported services. Without it, the page shows up at the top level of the sidebar.

It is recommended to add documentation for non-trivial tasks. For example, grafana

documentation mentions how to change the default database backend.

Documentation

The docs are Markdown files in ./doc, rendered with emanote by doc/flake.nix (based on emanote-template), and published to https://services.nixos.asia by .github/workflows/pages.yaml. Emanote’s authoring guide documents the note syntax — frontmatter, wikilinks, and folgezettel parents.

To preview the docs with live reloading:

just doc # Or, `cd doc && nix run`

To build the static site (this is what gets deployed):

just doc-static # Or, `nix build ./doc`