mirror of
https://github.com/juspay/services-flake.git
synced 2024-08-16 15:50:38 +03:00
[Docs] Home page and getting started (#83)
This commit is contained in:
parent
eb8361b9ab
commit
8c396234dc
15
README.md
15
README.md
@ -1,12 +1,8 @@
|
||||
# services-flake
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 🚧 Work in Progress
|
||||
|
||||
NixOS-like services for Nix flakes, as a [process-compose-flake](https://github.com/Platonic-Systems/process-compose-flake) module (based on flake-parts).
|
||||
|
||||
![](./doc/demo.gif)
|
||||
![](./doc/services-flake/demo.gif)
|
||||
|
||||
## Getting Started
|
||||
|
||||
@ -20,14 +16,7 @@ Or see `./test/flake.nix`
|
||||
|
||||
## Services available
|
||||
|
||||
- [x] Apache Kafka
|
||||
- [x] Elasticsearch
|
||||
- [x] MySQL
|
||||
- [x] PostgreSQL
|
||||
- [x] Redis
|
||||
- [x] Redis Cluster
|
||||
- [x] Zookeeper
|
||||
- [ ] ...
|
||||
See the list [here](nix/default.nix).
|
||||
|
||||
## A note on process working directory
|
||||
|
||||
|
284
doc/flake.lock
Normal file
284
doc/flake.lock
Normal file
@ -0,0 +1,284 @@
|
||||
{
|
||||
"nodes": {
|
||||
"commonmark-simple": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1705078713,
|
||||
"narHash": "sha256-YgDHJG8M47ZXGLWu8o7MhXbIrgQ0Ai32Gr8nKvZGGw8=",
|
||||
"owner": "srid",
|
||||
"repo": "commonmark-simple",
|
||||
"rev": "fc106c94f781f6a35ef66900880edc08cbe3b034",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "commonmark-simple",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"commonmark-wikilink": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1705502834,
|
||||
"narHash": "sha256-79fzI4fPhCkfusDXctQwwmjIcWMrLfTvUtKBY32asuM=",
|
||||
"owner": "srid",
|
||||
"repo": "commonmark-wikilink",
|
||||
"rev": "f6d7bdf7f1fce09ba2a4259b0306b0eef24c0cf7",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "commonmark-wikilink",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"ema": {
|
||||
"inputs": {
|
||||
"flake-parts": [
|
||||
"emanote",
|
||||
"flake-parts"
|
||||
],
|
||||
"flake-root": [
|
||||
"emanote",
|
||||
"flake-root"
|
||||
],
|
||||
"haskell-flake": [
|
||||
"emanote",
|
||||
"haskell-flake"
|
||||
],
|
||||
"nixpkgs": [
|
||||
"emanote",
|
||||
"nixpkgs"
|
||||
],
|
||||
"treefmt-nix": [
|
||||
"emanote",
|
||||
"treefmt-nix"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1702334080,
|
||||
"narHash": "sha256-zrtzyLrSORxtocLMji5U9p4pDicMulOqgsuiB4LCu1o=",
|
||||
"owner": "srid",
|
||||
"repo": "ema",
|
||||
"rev": "33f4cf31ace7e612e78ad25f5fc45089745ab644",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"ref": "no-ws",
|
||||
"repo": "ema",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"emanote": {
|
||||
"inputs": {
|
||||
"commonmark-simple": "commonmark-simple",
|
||||
"commonmark-wikilink": "commonmark-wikilink",
|
||||
"ema": "ema",
|
||||
"emanote-template": "emanote-template",
|
||||
"flake-parts": "flake-parts",
|
||||
"flake-root": "flake-root",
|
||||
"haskell-flake": "haskell-flake",
|
||||
"heist-extra": "heist-extra",
|
||||
"nixpkgs": "nixpkgs",
|
||||
"systems": "systems",
|
||||
"treefmt-nix": "treefmt-nix",
|
||||
"unionmount": "unionmount"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1705667811,
|
||||
"narHash": "sha256-ZH/m5e4l4v2HRcv45trQKl92PRG6e1lpRJ4+U4zewL8=",
|
||||
"owner": "srid",
|
||||
"repo": "emanote",
|
||||
"rev": "bf573e7653d183baa0fa68e2e172333f585b7a25",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "emanote",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"emanote-template": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1703877265,
|
||||
"narHash": "sha256-2xdikzzHrIHr1s2pAJrBJU8mZP258Na3V4P4RWteDZM=",
|
||||
"owner": "srid",
|
||||
"repo": "emanote-template",
|
||||
"rev": "9d458b63c80162519ae55814e60f17cc9d3f95a3",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "emanote-template",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"flake-parts": {
|
||||
"inputs": {
|
||||
"nixpkgs-lib": "nixpkgs-lib"
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1704982712,
|
||||
"narHash": "sha256-2Ptt+9h8dczgle2Oo6z5ni5rt/uLMG47UFTR1ry/wgg=",
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"rev": "07f6395285469419cf9d078f59b5b49993198c00",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "hercules-ci",
|
||||
"repo": "flake-parts",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"flake-root": {
|
||||
"locked": {
|
||||
"lastModified": 1692742795,
|
||||
"narHash": "sha256-f+Y0YhVCIJ06LemO+3Xx00lIcqQxSKJHXT/yk1RTKxw=",
|
||||
"owner": "srid",
|
||||
"repo": "flake-root",
|
||||
"rev": "d9a70d9c7a5fd7f3258ccf48da9335e9b47c3937",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "flake-root",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"haskell-flake": {
|
||||
"locked": {
|
||||
"lastModified": 1705067885,
|
||||
"narHash": "sha256-al2JqNIkXfLiVreqSJWly64Z6YVNphWBh4m3IxGIdYI=",
|
||||
"owner": "srid",
|
||||
"repo": "haskell-flake",
|
||||
"rev": "8a526aaf98cde6af6b2d1d368e9acb460ee34547",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "haskell-flake",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"heist-extra": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1691619499,
|
||||
"narHash": "sha256-4e8v5t4FM99pdcPhohP3dAeGtsFnirbfYGpbr2+qWxI=",
|
||||
"owner": "srid",
|
||||
"repo": "heist-extra",
|
||||
"rev": "54ff970f733dd45b5509d1c4c298927b6241041b",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "heist-extra",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs": {
|
||||
"locked": {
|
||||
"lastModified": 1704842529,
|
||||
"narHash": "sha256-OTeQA+F8d/Evad33JMfuXC89VMetQbsU4qcaePchGr4=",
|
||||
"owner": "nixos",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "eabe8d3eface69f5bb16c18f8662a702f50c20d5",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nixos",
|
||||
"ref": "nixpkgs-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"nixpkgs-lib": {
|
||||
"locked": {
|
||||
"dir": "lib",
|
||||
"lastModified": 1703961334,
|
||||
"narHash": "sha256-M1mV/Cq+pgjk0rt6VxoyyD+O8cOUiai8t9Q6Yyq4noY=",
|
||||
"owner": "NixOS",
|
||||
"repo": "nixpkgs",
|
||||
"rev": "b0d36bd0a420ecee3bc916c91886caca87c894e9",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"dir": "lib",
|
||||
"owner": "NixOS",
|
||||
"ref": "nixos-unstable",
|
||||
"repo": "nixpkgs",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"root": {
|
||||
"inputs": {
|
||||
"emanote": "emanote",
|
||||
"flake-parts": [
|
||||
"emanote",
|
||||
"flake-parts"
|
||||
],
|
||||
"nixpkgs": [
|
||||
"emanote",
|
||||
"nixpkgs"
|
||||
]
|
||||
}
|
||||
},
|
||||
"systems": {
|
||||
"locked": {
|
||||
"lastModified": 1681028828,
|
||||
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
|
||||
"owner": "nix-systems",
|
||||
"repo": "default",
|
||||
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-systems",
|
||||
"repo": "default",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"treefmt-nix": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"emanote",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1693468138,
|
||||
"narHash": "sha256-DddblCahuTW8K0ncPOheTlG3igE8b15LJjafF1PWhOo=",
|
||||
"owner": "numtide",
|
||||
"repo": "treefmt-nix",
|
||||
"rev": "6930a5ba0a722385baf273885a03f561dcb1af67",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "numtide",
|
||||
"repo": "treefmt-nix",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"unionmount": {
|
||||
"flake": false,
|
||||
"locked": {
|
||||
"lastModified": 1691619410,
|
||||
"narHash": "sha256-V9/OcGu9cy4kV9jta12A6w5BEj8awSEVYrXPpg8YckQ=",
|
||||
"owner": "srid",
|
||||
"repo": "unionmount",
|
||||
"rev": "ed73b627f88c8f021f41ba4b518ba41beff9df42",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "srid",
|
||||
"repo": "unionmount",
|
||||
"type": "github"
|
||||
}
|
||||
}
|
||||
},
|
||||
"root": "root",
|
||||
"version": 7
|
||||
}
|
36
doc/flake.nix
Normal file
36
doc/flake.nix
Normal file
@ -0,0 +1,36 @@
|
||||
{
|
||||
nixConfig = {
|
||||
extra-substituters = "https://srid.cachix.org";
|
||||
extra-trusted-public-keys = "srid.cachix.org-1:3clnql5gjbJNEvhA/WQp7nrZlBptwpXnUk6JAv8aB2M=";
|
||||
};
|
||||
|
||||
inputs = {
|
||||
emanote.url = "github:srid/emanote";
|
||||
nixpkgs.follows = "emanote/nixpkgs";
|
||||
flake-parts.follows = "emanote/flake-parts";
|
||||
};
|
||||
|
||||
outputs = inputs@{ self, flake-parts, nixpkgs, ... }:
|
||||
flake-parts.lib.mkFlake { inherit inputs; } {
|
||||
systems = nixpkgs.lib.systems.flakeExposed;
|
||||
imports = [ inputs.emanote.flakeModule ];
|
||||
perSystem = { self', pkgs, system, ... }: {
|
||||
emanote = {
|
||||
# By default, the 'emanote' flake input is used.
|
||||
# package = inputs.emanote.packages.${system}.default;
|
||||
sites."default" = {
|
||||
layers = [ ./. ];
|
||||
layersString = [ "." ];
|
||||
port = 8181;
|
||||
prettyUrls = true;
|
||||
};
|
||||
};
|
||||
devShells.default = pkgs.mkShell {
|
||||
buildInputs = [
|
||||
pkgs.nixpkgs-fmt
|
||||
];
|
||||
};
|
||||
formatter = pkgs.nixpkgs-fmt;
|
||||
};
|
||||
};
|
||||
}
|
@ -9,11 +9,21 @@ emanote:
|
||||
|
||||
# Running services using `services-flake`
|
||||
|
||||
[services-flake][gh] is a [flake-parts](https://flake.parts/) module providing NixOS-like services for Nix flakes. 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.
|
||||
[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.
|
||||
|
||||
>[!warning] Work in progress
|
||||
> `services-flake` is still being developed. Visit the [GitHub repository][gh] for more information.
|
||||
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.
|
||||
|
||||
![](services-flake/demo.gif)
|
||||
See:
|
||||
- [[start]]#
|
||||
- [[services]]#
|
||||
|
||||
## Demo
|
||||
|
||||
This is how running a service with `services-flake` looks like[^demo]:
|
||||
:::{.max-w-2xl .h-auto .mx-auto .p-4}
|
||||
![[demo.gif]]
|
||||
:::
|
||||
|
||||
[^demo]: The commands used in the demo are available in the [getting started](https://github.com/juspay/services-flake#getting-started) section of the `services-flake` README.
|
||||
|
||||
[gh]: https://github.com/juspay/services-flake
|
||||
|
@ -3,6 +3,8 @@
|
||||
|
||||
page:
|
||||
siteTitle: services-flake
|
||||
headHtml: |
|
||||
<snippet var="js.highlightjs" />
|
||||
|
||||
template:
|
||||
# You can add your own variables here, like editBaseUrl.
|
||||
|
Binary file not shown.
Before Width: | Height: | Size: 420 KiB After Width: | Height: | Size: 276 KiB |
20
doc/services-flake/services.md
Normal file
20
doc/services-flake/services.md
Normal file
@ -0,0 +1,20 @@
|
||||
---
|
||||
short-title: Services
|
||||
---
|
||||
|
||||
# Supported services
|
||||
|
||||
>[!warning]
|
||||
> This list denotes the progress of documentation, not implementation. See full list of implemented services at [gh].
|
||||
|
||||
- [ ] Apache Kafka
|
||||
- [ ] Elasticsearch
|
||||
- [ ] MySQL
|
||||
- [ ] Nginx
|
||||
- [ ] PostgreSQL
|
||||
- [ ] Redis
|
||||
- [ ] Redis Cluster
|
||||
- [ ] Zookeeper
|
||||
- [ ] ...
|
||||
|
||||
[gh]: https://github.com/juspay/services-flake
|
60
doc/services-flake/start.md
Normal file
60
doc/services-flake/start.md
Normal file
@ -0,0 +1,60 @@
|
||||
---
|
||||
order: -10
|
||||
---
|
||||
|
||||
# Getting started
|
||||
|
||||
|
||||
## New project
|
||||
|
||||
Use the [template flake](https://github.com/juspay/services-flake/blob/main/example/flake.nix) provided by `services-flake`:
|
||||
```sh
|
||||
mkdir example && cd ./example
|
||||
nix flake init -t github:juspay/services-flake
|
||||
nix run
|
||||
```
|
||||
|
||||
## Existing project
|
||||
|
||||
services-flake uses [process-compose-flake](https://community.flake.parts/process-compose-flake) to manage the services. Let's first import the `flake-parts` modules provided by `process-compose-flake` and `services-flake` in your flake:
|
||||
```nix
|
||||
{
|
||||
inputs.process-compose-flake.url = "github:Platonic-Systems/process-compose-flake";
|
||||
inputs.services-flake.url = "github:juspay/services-flake";
|
||||
...
|
||||
outputs = inputs:
|
||||
inputs.flake-parts.lib.mkFlake { inherit inputs; } {
|
||||
imports = [
|
||||
inputs.process-compose-flake.flakeModule
|
||||
];
|
||||
perSystem = { ... }: {
|
||||
process-compose."default" = {
|
||||
imports = [
|
||||
inputs.services-flake.processComposeModules.default
|
||||
];
|
||||
};
|
||||
}
|
||||
};
|
||||
}
|
||||
```
|
||||
As an example, let's add the `redis` service to your flake:
|
||||
```nix
|
||||
# Inside `perSystem.process-compose.default`
|
||||
{
|
||||
services.redis."r1".enable = true;
|
||||
}
|
||||
```
|
||||
|
||||
Time to run the service:
|
||||
```sh
|
||||
nix run
|
||||
```
|
||||
|
||||
## Under the hood
|
||||
|
||||
- The `services-flake` module configures [process settings](https://community.flake.parts/process-compose-flake#usage) for a service. In simple terms, it handles stuff like health checks, restart policies, setup scripts, etc. by using the easy to configure APIs provided by `process-compose-flake`.
|
||||
- The `process-compose-flake` module uses these settings to generate `packages.${system}.default`[^how-default] (`nix run` above, runs this package by default), which runs [process-compose](https://github.com/F1bonacc1/process-compose) with the generated YAML configuration[^sample-config].
|
||||
|
||||
[^how-default]: `default` is the name of the process group that is derived from `process-compose.<name>` in `perSystem.process-compose`.
|
||||
|
||||
[^sample-config]: See the example configuration from the [getting started](https://f1bonacc1.github.io/process-compose/intro/) section of the process-compose docs.
|
Loading…
Reference in New Issue
Block a user