mirror of
https://github.com/juspay/services-flake.git
synced 2024-09-19 16:27:29 +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
|
.direnv
|
||||||
# created when `just test <service>` is used
|
# created when `just test <service>` is used
|
||||||
/result
|
/result
|
||||||
|
# created when `just run <service>` is used
|
||||||
|
/test/data
|
||||||
|
19
README.md
19
README.md
@ -2,19 +2,13 @@
|
|||||||
|
|
||||||
# services-flake
|
# 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
|
## Getting Started
|
||||||
|
|
||||||
```sh
|
See <https://community.flake.parts/services-flake/start>
|
||||||
$ nix flake new --template github:juspay/services-flake ./my-project
|
|
||||||
$ cd my-project
|
|
||||||
$ nix run
|
|
||||||
```
|
|
||||||
|
|
||||||
Or see `./test/flake.nix`
|
|
||||||
|
|
||||||
## Services available
|
## 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).
|
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.
|
See <https://community.flake.parts/services-flake/contributing>
|
||||||
- For contributing to docs, see https://github.com/flake-parts/community.flake.parts#guidelines-for-writing-docs
|
|
||||||
|
|
||||||
## Credits
|
## 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?
|
### 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:
|
To change the database to `postgres`, we can use the following config:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
services.postgres.pg1 = {
|
{
|
||||||
enable = true;
|
services.postgres.pg1 = {
|
||||||
listen_addresses = "127.0.0.1";
|
enable = true;
|
||||||
initialScript.after = "CREATE USER root SUPERUSER;";
|
listen_addresses = "127.0.0.1";
|
||||||
};
|
initialScript.after = "CREATE USER root SUPERUSER;";
|
||||||
services.grafana.gf1 = {
|
};
|
||||||
enable = true;
|
services.grafana.gf1 = {
|
||||||
extraConf.database = with config.services.postgres.pg1; {
|
enable = true;
|
||||||
type = "postgres";
|
extraConf.database = with config.services.postgres.pg1; {
|
||||||
host = "${listen_addresses}:${builtins.toString port}";
|
type = "postgres";
|
||||||
name = "postgres"; # database name
|
host = "${listen_addresses}:${builtins.toString port}";
|
||||||
};
|
name = "postgres"; # database name
|
||||||
};
|
|
||||||
settings.processes."gf1".depends_on."pg1".condition = "process_healthy";
|
|
||||||
};
|
};
|
||||||
|
};
|
||||||
|
settings.processes."gf1".depends_on."pg1".condition = "process_healthy";
|
||||||
|
};
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
@ -9,9 +9,9 @@ emanote:
|
|||||||
|
|
||||||
# Running services using `services-flake`
|
# 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:
|
See:
|
||||||
- [[start]]#
|
- [[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].
|
> This list denotes the progress of documentation, not implementation. See full list of implemented services at [gh].
|
||||||
|
|
||||||
- [ ] Apache Kafka
|
- [ ] Apache Kafka
|
||||||
- [ ] [[clickhouse]]#
|
- [x] [[clickhouse]]#
|
||||||
- [ ] Elasticsearch
|
- [ ] Elasticsearch
|
||||||
- [ ] MySQL
|
- [ ] MySQL
|
||||||
- [ ] Nginx
|
- [ ] Nginx
|
||||||
@ -16,7 +16,7 @@ short-title: Services
|
|||||||
- [ ] Redis
|
- [ ] Redis
|
||||||
- [ ] Redis Cluster
|
- [ ] Redis Cluster
|
||||||
- [ ] Zookeeper
|
- [ ] Zookeeper
|
||||||
- [ ] [[grafana]]#
|
- [x] [[grafana]]#
|
||||||
- [ ] ...
|
- [ ] ...
|
||||||
|
|
||||||
[gh]: https://github.com/juspay/services-flake
|
[gh]: https://github.com/juspay/services-flake
|
||||||
|
9
justfile
9
justfile
@ -1,3 +1,4 @@
|
|||||||
|
# List all the just commands
|
||||||
default:
|
default:
|
||||||
@just --list
|
@just --list
|
||||||
|
|
||||||
@ -17,3 +18,11 @@ test-all:
|
|||||||
# Run native test for a specific service
|
# Run native test for a specific service
|
||||||
test service:
|
test service:
|
||||||
nix build ./test#checks.$(nix eval --impure --expr "builtins.currentSystem").{{service}} --override-input services-flake . -L
|
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