mirror of
https://github.com/juspay/services-flake.git
synced 2024-09-19 08:17:11 +03:00
Development and contribution guidelines (#112)
--------- Co-authored-by: Sridhar Ratnakumar <srid@srid.ca> Co-authored-by: Sridhar Ratnakumar <3998+srid@users.noreply.github.com>
This commit is contained in:
parent
0787c48b02
commit
c0a1021f54
2
.gitignore
vendored
2
.gitignore
vendored
@ -1,3 +1,5 @@
|
||||
.direnv
|
||||
# created when `just test <service>` is used
|
||||
/result
|
||||
# created when `just run <service>` is used
|
||||
/test/data
|
||||
|
19
README.md
19
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 <https://community.flake.parts/services-flake/start>
|
||||
|
||||
## 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 <https://community.flake.parts/services-flake/contributing>
|
||||
|
||||
## 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 <https://github.com/cachix/devenv/issues/75>
|
||||
|
75
doc/contributing.md
Normal file
75
doc/contributing.md
Normal file
@ -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 <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/<service-name>.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/<service-name>_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 <service-name>
|
||||
```
|
||||
|
||||
{#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 <service-name>
|
||||
```
|
||||
|
||||
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/<service-name>.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 <https://github.com/flake-parts/community.flake.parts#guidelines-for-writing-docs>
|
||||
|
||||
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`
|
||||
```
|
||||
|
@ -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";
|
||||
};
|
||||
}
|
||||
```
|
||||
|
@ -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]]#
|
||||
|
@ -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
|
||||
|
9
justfile
9
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 `<service>_test.nix`
|
||||
run service:
|
||||
cd test && nix run .#{{service}} --override-input services-flake ../
|
||||
|
Loading…
Reference in New Issue
Block a user