diff --git a/doc/manual/advanced-options.xml b/doc/manual/advanced-options.xml index 7a72e658..ed455458 100644 --- a/doc/manual/advanced-options.xml +++ b/doc/manual/advanced-options.xml @@ -277,7 +277,7 @@ ZipcodeService = { - It also possible to map a service to multple containers on multiple machines. This line states that the StaffTracker service should be deployed + It also possible to map a service to multiple containers on multiple machines. This line states that the StaffTracker service should be deployed to both the first and second Apache Tomcat container on machine test1. diff --git a/doc/manual/architecture.xml b/doc/manual/architecture.xml index 9b1bb3c2..2d5b0b5f 100644 --- a/doc/manual/architecture.xml +++ b/doc/manual/architecture.xml @@ -5,7 +5,7 @@ Architecture - Disnix is not a self-contained toolset and has a modular and extensible architecture. + Disnix is not a self-contained toolset. Instead, it has a modular and extensible architecture. This chapter describes the architecture of Disnix and shows how certain low-level activities can be performed. diff --git a/doc/manual/basicusage.xml b/doc/manual/basicusage.xml index c5744672..a1ca9a5e 100644 --- a/doc/manual/basicusage.xml +++ b/doc/manual/basicusage.xml @@ -62,7 +62,7 @@ a data layer, service layer and presentation layer. The database layer contains MySQL databases, storing data records such as zipcodes and staff members. - The web service layer contains web service components, which expose + The web service layer contains web service components exposing create, read, update and delete operations for each data set (the GeolocationService uses GeoIP to track a location). In the presentation layer, the StaffTracker @@ -78,7 +78,7 @@ the StaffTracker web application front-end. The arrows denote inter-dependency relationships. Inter-dependency correspond to network links between services. In this particular example, they - are SOAP/HTTP or plain TCP connections. + are SOAP/HTTP or "plain" TCP connections. @@ -194,8 +194,8 @@ stdenv.mkDerivation { - We can also specify some meta data for a package, so that we have a description - and other useful information, such as the homepage and a license. These properties are not used + We can also specify meta data attributes for a package, so that we have a description + and other kinds of useful information, such as the homepage and a license. These properties are not used while building the package. @@ -248,7 +248,7 @@ rec { Here, the expression defined in is imported and called - with the its required function parameters. The corresponding dependencies are + with its required function parameters. The corresponding dependencies are composed in the same composition expression shown in . @@ -347,7 +347,7 @@ stdenv.mkDerivation { shows a Disnix expression for a particular web service component of the StaffTracker - system, called ZipcodeService, which provides access + system, called ZipcodeService, providing access to records in the zipcode database. A Disnix expression is a nested function (having two function headers instead of one). @@ -363,7 +363,7 @@ stdenv.mkDerivation { - stdenv is provides an environment containing + stdenv provides an environment containing basic UNIX utilities and build environment. @@ -405,7 +405,7 @@ stdenv.mkDerivation { Each target attribute set defines two properties. The properties attribute refers to general machine properties and correspond to the properties attribute defined in the infrastructure model. - The container attribute refers to the set of container properties to which the services + The container attribute refers to the set of container properties to which the service has been deployed. @@ -461,7 +461,7 @@ stdenv.mkDerivation { Like ordinary Nix expressions, we cannot use the expression in directly to build the service. We need to compose it by calling the function with its required arguments. With Disnix, we need to compose a service twice. First, we have to compose this expression locally, - by calling it with the required intra-dependency arguments. Later, we have to compose it + by calling it with the required intra-dependency arguments. Later, we also have to compose it using the inter-dependency arguments. @@ -590,7 +590,7 @@ rec { zipcodes = { name = "zipcodes"; pkg = customPkgs.zipcodes; - dependsOn = {}; + dependsOn = {}; type = "mysql-database"; }; ... @@ -698,7 +698,7 @@ rec { - For every service, we must know how to build it and what their intra- and inter-dependencies are. + For every service, we must know how to build it and what their intra- and inter-dependencies are. This attribute refers to the intra-dependency closure of the service, which is composed in . @@ -706,7 +706,7 @@ rec { - We also need to know for each service what the inter-dependencies actually are. + We also need to know for each service what the inter-dependencies actually are. Inter-dependencies correspond to the arrows shown in . @@ -741,8 +741,8 @@ rec { The package type can be used to indicate that the service is an ordinary Nix package that should be deployed remotely. Services of this type will be installed, but no additional deployment - steps will be performed, such activation or deactivation. Additional steps besides installing are not - necessary for packages. See for more information. + steps will be performed, such activation or deactivation. Additional activities beyond installing are not + required for packages. See for more information. @@ -854,7 +854,7 @@ rec { The infrastructure model also allows you to specify a number of advanced system properties. These properties are - optional and typically reasonable default values are provided for them. They only need to be specified in special circumstances: + optional. In most scenarios, reasonable default values are provided for them. They only need to be specified in special circumstances: @@ -876,7 +876,7 @@ rec { This property is particularly useful when deploying to a heterogeneous network consisting of machines running various kinds of operating systems having various kinds of system architectures. - You do not need a dedicated cluster of machines to build for these architecture, but you can + You do not need a dedicated cluster of machines to build for these architectures, but you can reuse the existing deployment infrastructure. diff --git a/doc/manual/dysnomia-modules.xml b/doc/manual/dysnomia-modules.xml index f33d504f..e3386340 100644 --- a/doc/manual/dysnomia-modules.xml +++ b/doc/manual/dysnomia-modules.xml @@ -57,12 +57,8 @@ export prefix=@prefix@ # Import utility functions source @datadir@/@PACKAGE@/util -determineComponentName $2 -checkStateDir -determineTypeIdentifier $0 -composeSnapshotsPath -composeGarbagePath -composeGenerationsPath +# Sets a number of common utility environment variables +composeUtilityVariables $0 $2 $3 case "$1" in activate) @@ -78,10 +74,10 @@ case "$1" in fi ) | @mysql@ --user=$mysqlUsername --password=$mysqlPassword -N fi - unmarkStateAsGarbage + markComponentAsActive ;; deactivate) - markStateAsGarbage + markComponentAsGarbage ;; snapshot) tmpdir=$(mktemp -d) @@ -102,7 +98,7 @@ case "$1" in createGenerationSymlink $snapshotsPath/$hash ;; restore) - determineLastSnapshot + lastSnapshot=$(determineLastSnapshot) if [ "$lastSnapshot" != "" ] then @@ -112,10 +108,10 @@ case "$1" in fi ;; collect-garbage) - if [ -f $garbagePath ] + if componentMarkedAsGarbage then echo "drop database $componentName;" | @mysql@ --user=$mysqlUsername --password=$mysqlPassword -N - unmarkStateAsGarbage + unmarkComponentAsGarbage fi ;; esac diff --git a/doc/manual/extensions.xml b/doc/manual/extensions.xml index a3b23dcd..1a1581aa 100644 --- a/doc/manual/extensions.xml +++ b/doc/manual/extensions.xml @@ -5,7 +5,7 @@ Extensions - Although Disnix makes the deployment of a distributed system more convenient and + Although Disnix makes it possible to automate the deployment of a service-oriented system and offers various kinds of features to make this process reliable and efficient, some extensions have been developed to make deployment processes more convenient. diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml index 232017c9..346f6d37 100644 --- a/doc/manual/installation.xml +++ b/doc/manual/installation.xml @@ -23,7 +23,7 @@ Deploying NixOS-based configurations is quite straight forward. A coordinator machine simply requires the presence of the Dysnomia and Disnix utilities in the system environment or a Nix user - profile. Each target machine requires the Disnix service to be deployed and a number of + profile. Each target machine requires the presence of a Disnix service instance and (optionally) a number of container services.
@@ -69,7 +69,7 @@ services.openssh.enable = true; Besides SSH it also possible to use other kinds of communication protocols. - has more information on this. + provides more information on this. @@ -103,8 +103,8 @@ services.tomcat.enable = true; Installing Dysnomia from source - The dysnomia package is GNU Autotools based, - which must be installed by executing the following commands: + The dysnomia package is GNU Autotools based + and must be installed by executing the following commands: @@ -163,7 +163,7 @@ $ ./configure --help help2man to generate manual pages and doclifter to generate - docbook pages from the generated manual pages. + Docbook pages from the generated manual pages. Since Disnix is built on top of the @@ -341,13 +341,13 @@ exit 0 Refer to your distribution's init.d script style to see how services are configured and launched. For convenience, a Debian-compatible init.d script named - disnix-service.initd has been placed in the $PREFIX/share/doc folder - of this package. + disnix-service.initd has been placed in the $PREFIX/share/doc + sub folder of this package. An important aspect to keep in mind is that both Nix and Dysnomia should be in the PATH of the init.d script so that the service can execute all required deployment activities. - Another important thing is that the Disnix service should be started after the D-Bus system service and stopped + Moreover, the Disnix service should be started after the D-Bus system service and stopped in exactly the opposite order. @@ -387,7 +387,7 @@ $ cygrunsrv -I disnix -p /usr/local/bin/disnix-service.exe \ The parameter specifies under which the Disnix - service runs. If a single user Nix installation has been performed, + service runs. If a single user Nix installation has been performed, this username should be substituted by the actual username under which Disnix has been installed. In multi-user Nix installations, the parameter should @@ -497,7 +497,7 @@ type=mysql-database
- A Dysnomia container configuration file for a MySQL server + A Dysnomia component configuration file for a MySQL server create table author diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml index 65aaa488..ce8401bb 100644 --- a/doc/manual/introduction.xml +++ b/doc/manual/introduction.xml @@ -8,8 +8,8 @@ Disnix is a distributed service deployment toolset which main purpose is to deploy service-oriented systems (i.e. systems that can be decomposed into "distributable units") into networks of machines - having various characteristics (such as operating systems) and is built on top of Nix; - a package manager which has some unique features compared to conventional package + having various characteristics (such as operating systems). Disnix is built on top of Nix -- + a package manager that has a number of powerful and unique advantages over conventional package managers to make deployment safe, reliable, and reproducible. @@ -58,7 +58,7 @@ Moreover, Nix uses a purely functional domain-specific language called the Nix expression language - to specify build actions. Using a purely functional language makes builds deterministic and reproducable. + to specify build actions. Using a purely functional language makes builds deterministic and reproducible. A garbage collector is included to safely remove packages that are no longer in use. @@ -84,7 +84,7 @@ Like the standard Nix deployment system, Disnix uses the Nix expression language, which is used to write - specifications for the deployment of distributed + specifications for the deployment of service-oriented systems. @@ -171,7 +171,7 @@ Apart from the portability of Disnix itself, Disnix also allows a user to deploy a service oriented system into a heterogeneous network (i.e. a network consisting of various types of machines, running various operating systems). Disnix reuses - Nix's delegation mechanism to build a component for an alien target platform. + Nix's delegation mechanism to build a package for an alien target platform. Optionally, it can also delegate builds to the target machines in the network. diff --git a/doc/manual/overview.xml b/doc/manual/overview.xml index 81c13414..16adf508 100644 --- a/doc/manual/overview.xml +++ b/doc/manual/overview.xml @@ -5,7 +5,7 @@ Overview
- An overview of Disnix + An overview of Disnix @@ -17,7 +17,7 @@ The figure above illustrates Disnix's deployment concepts in a nutshell. In the center of the figure the disnix-env command line tool is shown, which takes care of performing a complete deployment - process of a distributed system. + process of a service-oriented system. This tool requires three models as input parameters shown @@ -28,7 +28,7 @@ The services model describes of which distributable components (called services) the system consists, their inter-dependencies and their types. The service model has a reference to a file named all-packages.nix, - which captures all the intra-dependency compositions of every service, + capturing all the intra-dependency compositions of every service, such as libraries, configuration files and compilers. @@ -88,11 +88,11 @@ $ disnix-env -s services.nix -i infrastructure.nix -d distribution.nix - Optionally, Disnix can also move the state of a service from machine to another. + Optionally, Disnix can move the state of a service from machine to another. For example, when deploying databases, Disnix only ensures that they are created with a schema and initial dataset. However, when the structure and contents of a database evolves, their changes are not migrated automatically. As a solution, Disnix has a mechanism that snapshots, moves and restores state of a service - if it has been explicitly enabled for that particular service. + if state management has been explicitly enabled for that particular service. diff --git a/doc/manual/packages.xml b/doc/manual/packages.xml index 2ba45dd3..09bdd03d 100644 --- a/doc/manual/packages.xml +++ b/doc/manual/packages.xml @@ -16,7 +16,7 @@ Specifying packages as services - In Nixpkgs, it it is a common habit to write each package specification as a function in which the parameters + In Nixpkgs, it is a common habit to write each package specification as a function in which the parameters denote intra-dependencies. In we have shown that Disnix services follow the same convention and extend this approach with nested functions in which the inner function takes inter-dependencies into account. diff --git a/doc/manual/state.xml b/doc/manual/state.xml index 36a6669b..1d4d96cb 100644 --- a/doc/manual/state.xml +++ b/doc/manual/state.xml @@ -18,7 +18,7 @@ In a large network of machines it can be quite costly to manage state manually. Disnix also provides - experimental state management facilities to cope with this. However, they are disabled by default. + experimental state management facilities to cope with this. However, state management is disabled by default. To manage state for a specific subset of services, they must be annotated as such in the services model. diff --git a/doc/manual/targetspecific.xml b/doc/manual/targetspecific.xml index cb04a1be..42b77bcd 100644 --- a/doc/manual/targetspecific.xml +++ b/doc/manual/targetspecific.xml @@ -352,7 +352,7 @@ builtins.listToAttrs (map (targetName: services = { nginx-wrapper-test2 = { name = "nginx-wrapper-test2"; - ... + ... }; webapp3 = ... webapp4 = ... diff --git a/scripts/Makefile.am b/scripts/Makefile.am index c05c0afa..61b1c6cf 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -9,7 +9,7 @@ disnix-instantiate.1.xml: disnix-instantiate.1 $(SHELL) ../maintenance/man2docbook.bash $< disnix-manifest.1: disnix-manifest.in - $(HELP2MAN) --output=$@ --no-info --name 'Generate a manifest file from Disnix expressions' "$(SHELL) disnix-manifest" + $(HELP2MAN) --output=$@ --no-info --name 'Generate a deployment manifest file from Disnix expressions' "$(SHELL) disnix-manifest" disnix-manifest.1.xml: disnix-manifest.1 $(SHELL) ../maintenance/man2docbook.bash $< diff --git a/src/dbus-service/Makefile.am b/src/dbus-service/Makefile.am index b9c64ca5..0a562556 100644 --- a/src/dbus-service/Makefile.am +++ b/src/dbus-service/Makefile.am @@ -1,11 +1,11 @@ disnix-client.1: disnix-client.c - $(HELP2MAN) --output=$@ --no-info --name 'Build store derivations on target machines in a network' --libtool ./disnix-client + $(HELP2MAN) --output=$@ --no-info --name 'Provides access to the disnix-service through the DBus system or session bus' --libtool ./disnix-client disnix-client.1.xml: disnix-client.1 $(SHELL) ../../maintenance/man2docbook.bash $< disnix-service.8: disnix-service-main.c - $(HELP2MAN) --output=$@ --no-info --name 'Build store derivations on target machines in a network' --section 8 --libtool ./disnix-service + $(HELP2MAN) --output=$@ --no-info --name 'Exposes Nix/Dysnomia deployment operations as a DBus service' --section 8 --libtool ./disnix-service disnix-service.8.xml: disnix-service.8 $(SHELL) ../../maintenance/man2docbook.bash $<