From c0a1021f5409b39909e6f4482e35b6930ffaa941 Mon Sep 17 00:00:00 2001 From: Shivaraj B H Date: Sat, 24 Feb 2024 17:54:57 +0530 Subject: [PATCH] Development and contribution guidelines (#112) --------- Co-authored-by: Sridhar Ratnakumar Co-authored-by: Sridhar Ratnakumar <3998+srid@users.noreply.github.com> --- .gitignore | 2 ++ README.md | 19 ++++-------- doc/contributing.md | 75 +++++++++++++++++++++++++++++++++++++++++++++ doc/grafana.md | 30 +++++++++--------- doc/index.md | 4 +-- doc/services.md | 4 +-- justfile | 9 ++++++ 7 files changed, 112 insertions(+), 31 deletions(-) create mode 100644 doc/contributing.md diff --git a/.gitignore b/.gitignore index 5b0a09d..2d58df9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ .direnv # created when `just test ` is used /result +# created when `just run ` is used +/test/data diff --git a/README.md b/README.md index d9b6c4a..3f92826 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,13 @@ # services-flake -NixOS-like services for Nix flakes, as a [process-compose-flake](https://github.com/Platonic-Systems/process-compose-flake) module (based on flake-parts). +Declarative, composable, and reproducible services for Nix development environment, as a [process-compose-flake](https://github.com/Platonic-Systems/process-compose-flake) module (based on [flake-parts](https://flake.parts)). Enabling users to have NixOS-like service on MacOS and Linux. -![](./doc/services-flake/demo.gif) +![Demo](./doc/demo.gif) ## Getting Started -```sh -$ nix flake new --template github:juspay/services-flake ./my-project -$ cd my-project -$ nix run -``` - -Or see `./test/flake.nix` +See ## Services available @@ -28,10 +22,9 @@ The `dataDir` of these services tend to take *relative* paths, which are usually To discuss the project, please [join our Zulip](https://nixos.zulipchat.com/#narrow/stream/414011-services-flake). -## Contributing +## Contributing & Development -- If you are adding a *new* service, see https://github.com/cachix/devenv/tree/main/src/modules/services for inspiration. -- For contributing to docs, see https://github.com/flake-parts/community.flake.parts#guidelines-for-writing-docs +See ## Credits @@ -41,4 +34,4 @@ Thanks to [the devenv project](https://github.com/cachix/devenv/tree/main/src/mo ### Why not re-use devenv service modules? -This is currently not possible (nor prioritized by the devenv project), which is why we must create our own services. See https://github.com/cachix/devenv/issues/75 +This is currently not possible (nor prioritized by the devenv project), which is why we must create our own services. See diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..a36d120 --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,75 @@ +--- +order: 10 +--- + +# Contributing + +{#devshell} +## Development Shell + +A Nix dev shell is available, providing `nixpkgs-fmt` and `just`. To enter the dev shell, run: + +```sh +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](https://nixos.asia/en/direnv). + +{#new-service} +## Adding a new service + +The project repository is structure to make addition of new services easy. Here's how to add a new service: + +> [!info] +> See for inspiration. +> +> If you don't find a new service there, see . + +- Create a new file `./nix/.nix` file (see [./nix/redis.nix](https://github.com/juspay/services-flake/blob/main/nix/redis.nix) for inspiration) +- Add the service to the list in [./nix/default.nix](https://github.com/juspay/services-flake/blob/main/nix/default.nix). +- Create a new test file `./nix/_test.nix` (see [./nix/redis_test.nix](https://github.com/juspay/services-flake/blob/main/nix/redis_test.nix)). +- Add the test to [./test/flake.nix](https://github.com/juspay/services-flake/blob/main/test/flake.nix). + +{#run-service} +### Run the service + +```sh +just run +``` + +{#run-tests} +### Run the tests for the service + +The previous command will run the services but not the tests. To run the tests, use: + +```sh +just test +``` + +or test all services: + +```sh +just test-all +``` + +{#service-doc} +### 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/.md` (see [[clickhouse]] for example) and add the service to the list in [[services]]. + +> [!note] +> It is recommended to add documentation for non-trivial tasks. For example, grafana documentation mentions [how to change the default database backend](https://community.flake.parts/services-flake/grafana#change-database). + + + +{#docs} +## Documentation + +For contributing to docs, see + +We use [emanote](https://emanote.srid.ca/) to render our documentation. The source files are in the `doc` directory. To run the docs, use: + +```sh +just doc # Or, `cd doc && nix run` +``` + diff --git a/doc/grafana.md b/doc/grafana.md index b2fce69..f49095d 100644 --- a/doc/grafana.md +++ b/doc/grafana.md @@ -22,19 +22,21 @@ By default, Grafana stores data in the `sqlite3` [database](https://grafana.com/ To change the database to `postgres`, we can use the following config: ```nix - services.postgres.pg1 = { - enable = true; - listen_addresses = "127.0.0.1"; - initialScript.after = "CREATE USER root SUPERUSER;"; - }; - services.grafana.gf1 = { - enable = true; - extraConf.database = with config.services.postgres.pg1; { - type = "postgres"; - host = "${listen_addresses}:${builtins.toString port}"; - name = "postgres"; # database name - }; - }; - settings.processes."gf1".depends_on."pg1".condition = "process_healthy"; +{ + services.postgres.pg1 = { + enable = true; + listen_addresses = "127.0.0.1"; + initialScript.after = "CREATE USER root SUPERUSER;"; + }; + services.grafana.gf1 = { + enable = true; + extraConf.database = with config.services.postgres.pg1; { + type = "postgres"; + host = "${listen_addresses}:${builtins.toString port}"; + name = "postgres"; # database name }; + }; + settings.processes."gf1".depends_on."pg1".condition = "process_healthy"; + }; +} ``` diff --git a/doc/index.md b/doc/index.md index 2ccae18..6cf6221 100644 --- a/doc/index.md +++ b/doc/index.md @@ -9,9 +9,9 @@ emanote: # Running services using `services-flake` -[services-flake][gh] is a [flake-parts](https://flake.parts/) module providing [NixOS-like services](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules/services) for [Nix flakes](https://nixos.asia/en/flakes), enabling the users to use same configuration for local development across platforms. +[services-flake][gh] provides declarative, composable, and reproducible services for Nix development environment, as a [process-compose-flake](https://github.com/Platonic-Systems/process-compose-flake) module (based on [flake-parts](https://flake.parts)). Enabling users to have NixOS-like service on MacOS and Linux. -It builds on top of the [process-compose-flake](https://community.flake.parts/process-compose-flake) module which allows running arbitrary processes in the devShell environment. +It builds on top of the [process-compose-flake](https://community.flake.parts/process-compose-flake) module which allows running arbitrary processes declared in Nix. See: - [[start]]# diff --git a/doc/services.md b/doc/services.md index 0478b02..184930a 100644 --- a/doc/services.md +++ b/doc/services.md @@ -8,7 +8,7 @@ short-title: Services > This list denotes the progress of documentation, not implementation. See full list of implemented services at [gh]. - [ ] Apache Kafka -- [ ] [[clickhouse]]# +- [x] [[clickhouse]]# - [ ] Elasticsearch - [ ] MySQL - [ ] Nginx @@ -16,7 +16,7 @@ short-title: Services - [ ] Redis - [ ] Redis Cluster - [ ] Zookeeper -- [ ] [[grafana]]# +- [x] [[grafana]]# - [ ] ... [gh]: https://github.com/juspay/services-flake diff --git a/justfile b/justfile index a2b6308..f9790ff 100644 --- a/justfile +++ b/justfile @@ -1,3 +1,4 @@ +# List all the just commands default: @just --list @@ -17,3 +18,11 @@ test-all: # Run native test for a specific service test service: nix build ./test#checks.$(nix eval --impure --expr "builtins.currentSystem").{{service}} --override-input services-flake . -L + +# Run doc server with hot-reload +doc: + cd ./doc && nix run + +# Run service whose configuration is defined in `_test.nix` +run service: + cd test && nix run .#{{service}} --override-input services-flake ../