services-flake/doc/start.md
Shivaraj B H 1ae2579853
docs: add motivation for creating services-flake (#125)
resolves #124 and #123

---------

Co-authored-by: Sridhar Ratnakumar <3998+srid@users.noreply.github.com>
2024-03-07 22:10:16 +05:30

2.4 KiB

order
-10

Getting started

New project

Use the template flake provided by services-flake:

mkdir example && cd ./example
nix flake init -t github:juspay/services-flake
nix run

Existing project

services-flake uses 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:

{
  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:

# Inside `perSystem.process-compose.default`
{
  services.redis."r1".enable = true;
}

Time to run the service:

nix run

Under the hood

  • The services-flake module configures process settings 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}.default1 (nix run above, runs this package by default), which runs process-compose with the generated YAML configuration2.

Examples

  • In Nammayatri, services-flakes is used to run the local services stack (which used to be run with docker-compose). Read about it in this blog post.

  1. default is the name of the process group that is derived from process-compose.<name> in perSystem.process-compose. ↩︎

  2. See the example configuration from the getting started section of the process-compose docs. ↩︎