Document the use cases of this services repository
This commit is contained in:
parent
653b6e5aee
commit
3f11dbfd4f
|
@ -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.
|
66
README.md
66
README.md
|
@ -4,8 +4,70 @@ This repository contains a collection of services that can be deployed with the
|
||||||
experimental
|
experimental
|
||||||
[Nix process management framework](https://github.com/svanderburg/nix-processmgmt).
|
[Nix process management framework](https://github.com/svanderburg/nix-processmgmt).
|
||||||
|
|
||||||
You can deploy them with multiple process managers, use them as unprivileged
|
You can deploy systems that are constructed from running process instances
|
||||||
user, and run multiple instances of them on the same machine.
|
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
|
License
|
||||||
=======
|
=======
|
||||||
|
|
Loading…
Reference in New Issue