Document the use cases of this services repository

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2020-2021 Sander van der Burg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -4,8 +4,70 @@ This repository contains a collection of services that can be deployed with the
 experimental
 [Nix process management framework](https://github.com/svanderburg/nix-processmgmt).
 
-You can deploy them with multiple process managers, use them as unprivileged
-user, and run multiple instances of them on the same machine.
+You can deploy systems that are constructed from running process instances
+managed by a process manager of choice, use them as an unprivileged user, and run
+multiple process instances on the same machine.
+
+Constructor functions
+=====================
+Process instances that are deployed by the Nix process management framework are
+typically constructed from *constructor functions*:
+
+* `services-agnostic/` folder contains constructor functions for all kinds of
+  commonly used services.
+* `service-containers-agnostic/` extends a subset of the constructor functions
+  with [Dysnomia](https://github.com/svanderburg/dysnomia) container
+  configuration files so that these services can become containers (deployment
+  targets) for [Disnix](https://github.com/svanderburg/disnix) deployments.
+
+Example deployments
+===================
+The `example-deployments/` folder contains deployment specifications for example
+systems that consist of multiple processes:
+
+* `services`: demonstrates how to deploy many kinds of commonly used services:
+  MySQL, PostgreSQL, Nginx, the Apache HTTP server, `svnserve`, Docker etc.
+* `hydra`: demonstrates how to deploy [Hydra](https://nixos.org/hydra): the
+  Nix-based continuous integration system
+
+Deploying the example systems
+=============================
+The above examples can be deployed by running any of the `nixproc-*-switch`
+tools provided by the Nix process management framework. Each process manager
+backend has its own implementation.
+
+For example, to deploy the system as sysvinit scripts, use:
+
+```bash
+$ nixproc-sysvinit-switch processes.nix
+```
+
+The above command needs to be run as root user, so that unprivileged users can
+be created for each service.
+
+To deploy a system as an unprivileged user, use:
+
+```bash
+$ nixproc-sysvinit-switch --state-dir $HOME/var --force-disable-user-change processes.nix
+```
+
+The above command-line parameters have the following purposes:
+* The `--state-dir` parameter changes the global state directory to the `var`
+  folder in the user's home directory.
+* `--force-disable-user-change` disables all user operations (e.g. creating
+  users, changing ownership), which an unprivileged user typically is not
+  allowed to do.
+
+To do a stateless deployment of the system with supervisord as an unprivileged
+user, use:
+
+```bash
+$ nixproc-supervisord-deploy-stateless --state-dir $HOME/var --force-disable-user-change processes.nix
+```
+
+The above command activates the system as a whole and keeps `supervisord`
+running in the foreground. Terminating `supervisord` causes the entire system
+to get deactivated.
 
 License
 =======