Author: sandervanderburg Date: Sun Jan 30 14:19:22 2011 New Revision: 25722 URL: https://svn.nixos.org/websvn/nix/?rev=25722&sc=1
Log: Added some documentation Added: disnix/examples/disnix-proxy-example/trunk/doc/ disnix/examples/disnix-proxy-example/trunk/doc/Makefile disnix/examples/disnix-proxy-example/trunk/doc/architecture-with-proxy.dia (contents, props changed) disnix/examples/disnix-proxy-example/trunk/doc/architecture-with-proxy.png (contents, props changed) disnix/examples/disnix-proxy-example/trunk/doc/architecture-without-proxy.dia (contents, props changed) disnix/examples/disnix-proxy-example/trunk/doc/architecture-without-proxy.png (contents, props changed) disnix/examples/disnix-proxy-example/trunk/doc/architecture.xml disnix/examples/disnix-proxy-example/trunk/doc/images/ disnix/examples/disnix-proxy-example/trunk/doc/index.xml disnix/examples/disnix-proxy-example/trunk/doc/introduction.xml disnix/examples/disnix-proxy-example/trunk/doc/style.css disnix/examples/disnix-proxy-example/trunk/doc/usage.xml Modified: disnix/examples/disnix-proxy-example/trunk/release-without-proxy.nix Added: disnix/examples/disnix-proxy-example/trunk/doc/Makefile ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/Makefile Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,53 @@ +INSTALL = install +docdir = /share/doc/disnix-proxy-example + +XMLLINT = xmllint +XSLTPROC = xsltproc \ + --param section.autolabel 1 \ + --param section.label.includes.component.label 1 \ + --param html.stylesheet \'style.css\' \ + --param make.valid.html 1 \ + --param xref.with.number.and.title 1 \ + --param toc.section.depth 3 \ + --param admon.style \'\' \ + --param callout.graphics.extension \'.gif\' \ + --param contrib.inline.enabled 0 + +dblatex = dblatex + +dblatex_opts = \ + -P doc.collab.show=0 \ + -P latex.output.revhistory=0 + +VERSION = $(shell cat ../version) + +MANUAL_SRCS = index.xml introduction.xml architecture.xml usage.xml + +FIGURES = architecture-with-proxy.png architecture-without-proxy.png + +all: index.html index.pdf + +version.txt: + echo -n $(VERSION) > version.txt + +manual.is-valid: $(MANUAL_SRCS) version.txt + $(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng $(docbookrng)/docbook.rng $< + touch $@ + +index.html: $(MANUAL_SRCS) manual.is-valid + $(XSLTPROC) --nonet --xinclude --output index.html \ + $(docbookxsl)/html/docbook.xsl index.xml + +index.pdf: $(MANUAL_SRCS) manual.is-valid + if test "$(dblatex)" != ""; then \ + $(dblatex) $(dblatex_opts) index.xml; \ + else \ + echo "Please install dblatex and rerun configure."; \ + exit 1; \ + fi + +install: index.html + $(INSTALL) -d $(DESTDIR)$(docdir)/manual + $(INSTALL) index.html $(DESTDIR)$(docdir)/manual + $(INSTALL) style.css $(DESTDIR)$(docdir)/manual + $(INSTALL) $(FIGURES) $(DESTDIR)$(docdir)/manual Added: disnix/examples/disnix-proxy-example/trunk/doc/architecture-with-proxy.dia ============================================================================== Binary file. No diff available. Added: disnix/examples/disnix-proxy-example/trunk/doc/architecture-with-proxy.png ============================================================================== Binary file. No diff available. Added: disnix/examples/disnix-proxy-example/trunk/doc/architecture-without-proxy.dia ============================================================================== Binary file. No diff available. Added: disnix/examples/disnix-proxy-example/trunk/doc/architecture-without-proxy.png ============================================================================== Binary file. No diff available. Added: disnix/examples/disnix-proxy-example/trunk/doc/architecture.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/architecture.xml Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,33 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-architecture"> + + <title>Architecture</title> + + <figure xml:id="fig-1-architecture-without-proxy"> + <title>Simple server and client</title> + <mediaobject> + <imageobject> + <imagedata fileref="architecture-without-proxy.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + + <figure xml:id="fig-2-architecture-with-proxy"> + <title>Simple server and client using a proxy</title> + <mediaobject> + <imageobject> + <imagedata fileref="architecture-with-proxy.png" format="PNG"/> + </imageobject> + </mediaobject> + </figure> + + <para> + <xref linkend="fig-1-architecture-without-proxy" /> shows the architecture of this example, + consisting of a server and a client. + The server is a daemon listening for messages from the client. If the server + receives 'hello', it will respond by returning a 'Hello world' message. + In <xref linkend="fig-2-architecture-with-proxy" /> the architecture is extended with a proxy. This proxy is notified by + Disnix if an upgrade starts, draining the connections to make an upgrade completely atomic. + </para> +</chapter> Added: disnix/examples/disnix-proxy-example/trunk/doc/index.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/index.xml Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,33 @@ +<book xmlns="http://docbook.org/ns/docbook"; + xmlns:xi="http://www.w3.org/2001/XInclude";> + + <info> + <title>Disnix TCP proxy example</title> + + <subtitle>Draft (Version <xi:include href="version.txt" parse="text" />)</subtitle> + + <author> + <personname> + <firstname>Sander</firstname> + <surname>van der Burg</surname> + </personname> + <affiliation> + <orgname>Delft University of Technology</orgname> + <orgdiv>Department of Software Technology</orgdiv> + </affiliation> + <contrib>Author</contrib> + </author> + + <copyright> + <year>2010</year> + <year>2011</year> + <holder>Sander van der Burg</holder> + </copyright> + + <date>January 2011</date> + </info> + + <xi:include href="introduction.xml" /> + <xi:include href="architecture.xml" /> + <xi:include href="usage.xml" /> +</book> Added: disnix/examples/disnix-proxy-example/trunk/doc/introduction.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/introduction.xml Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,20 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-introduction"> + + <title>Introduction</title> + + <para> + This is a trivial example case to demonstrate how upgrades can be made + completely atomic by means of a TCP proxy. The example system consists of + a very simple server and client communicating through a TCP socket. + By using an alternative composition the proxy is being used for communication + between the server and client, which is notified + by Disnix before the upgrade starts. The proxy then drains connections + during the upgrade. In this phase, Disnix waits until + there are no activate connections before it starts the actual upgrade. + New connections made by a client during this + phase are queued. If there are no activate connections the upgrade starts. + After the upgrade the proxy is notified to accept connections again. + </para> +</chapter> Added: disnix/examples/disnix-proxy-example/trunk/doc/style.css ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/style.css Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,29 @@ +body +{ + font-family: arial, lucida, helvetica, sans-serif; + font-size: 100%; +} + +h1 +{ + color: #0055aa; + font-size: 170%; +} + +h2 +{ + font-size: 150%; +} + +h3 +{ + font-size: 125%; +} + +pre.screen, pre.programlisting +{ + border-style: solid; + border-width: 1px; + background-color: #dddddd; + padding: 0.5em; +} Added: disnix/examples/disnix-proxy-example/trunk/doc/usage.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ disnix/examples/disnix-proxy-example/trunk/doc/usage.xml Sun Jan 30 14:19:22 2011 (r25722) @@ -0,0 +1,107 @@ +<chapter xmlns="http://docbook.org/ns/docbook"; + xmlns:xlink="http://www.w3.org/1999/xlink"; + xml:id="chap-usage"> + + <title>Usage</title> + + <para> + This example comes in two variants. You can either deploy the server and client + with or without proxy. There are three ways to try to deploy this example. + The <filename>deployment/DistributedDeployment</filename> folder contains all + neccessary Disnix models, such as a services, infrastructure and distribution + models required for deployment. + </para> + + <section> + <title>Deployment in a heterogeneous network</title> + + <para> + For this scenario only installation of the basic Disnix toolset is required. + First, you must manually install a network of machines running the Disnix service. + Then you must adapt the infrastructure model to match to properties of your network + and the distribution model to map the services to the right machines. + </para> + + <para> + The variant without proxy can be deployed by running the following command: +<screen> +$ disnix-env -s services-without-proxy.nix -i infrastructure.nix -d distribution-without-proxy.nix +</screen> + </para> + + <para> + The variant with proxy can be deployed by running the following command: + +<screen> +$ disnix-env -s services-with-proxy.nix -i infrastructure.nix -d distribution-with-proxy.nix +</screen> + </para> + </section> + + <section> + <title>Deployment using DisnixOS</title> + + <para> + For this scenario you need to install a network of NixOS machines, running the + Disnix service. This can be done by enabling the following configuration + option in each <filename>/etc/nixos/configuration.nix</filename> file: + +<screen> +services.disnix.enable = true; +</screen> + </para> + + <para> + You may also need to adapt the NixOS configurations to which the + <filename>network.nix</filename> model is referring, so that they will + match the actual system configurations. + </para> + + <para> + The system including its underlying infrastructure can be deployed + by using the <command>disnixos-env</command> command. The following + instruction deploys the variant without a proxy: + +<screen> +$ disnixos-env -s services-without-proxy.nix -n network.nix -d distribution-without-proxy.nix +</screen> + </para> + + <para> + The following instruction deploys the variant with a proxy: + +<screen> +$ disnixos-env -s services-with-proxy.nix -n network.nix -d distribution-with-proxy.nix +</screen> + </para> + </section> + + <section> + <title>Deployment using the DisnixOS virtualization feature</title> + + <para> + This system can be deployed without adapting any of the models in + <filename>deployment/DistributedDeployment</filename>. By running + the following instruction, the variant without the proxy can be deployed in a network + of virtual machines: + +<screen> +$ disnixos-vm-env -s services-without-proxy.nix -n network.nix -d distribution-without-proxy.nix +</screen> + </para> + + <para> + By running the following instruction, the variant with proxy can be deployed in a + network of virtual machines: + </para> + +<screen> +$ disnixos-vm-env -s services-with-proxy.nix -n network.nix -d distribution-with-proxy.nix +</screen> + + <para> + The disadvantage of using the virtualization extension is that no upgrades + can be performed and thus the locking mechanism cannot be used. + </para> + </section> +</chapter> Modified: disnix/examples/disnix-proxy-example/trunk/release-without-proxy.nix ============================================================================== --- disnix/examples/disnix-proxy-example/trunk/release-without-proxy.nix Sun Jan 30 08:25:04 2011 (r25721) +++ disnix/examples/disnix-proxy-example/trunk/release-without-proxy.nix Sun Jan 30 14:19:22 2011 (r25722) @@ -22,6 +22,33 @@ src = disnix_proxy_example; inherit officialRelease; }; + + doc = + { tarball ? jobs.tarball {} + , system ? "x86_64-linux" + }: + + with import nixpkgs { inherit system; }; + + releaseTools.nixBuild { + name = "disnix-proxy-example-doc"; + version = builtins.readFile ./version; + src = tarball; + buildInputs = [ libxml2 libxslt dblatex tetex ]; + + buildPhase = '' + cd doc + make docbookrng=${docbook5}/xml/rng/docbook docbookxsl=${docbook5_xsl}/xml/xsl/docbook + ''; + + checkPhase = "true"; + + installPhase = '' + make DESTDIR=$out install + + echo "doc manual $out/share/doc/disnix-proxy-example/manual" >> $out/nix-support/hydra-build-products + ''; + }; build = { tarball ? jobs.tarball {} _______________________________________________ nix-commits mailing list [email protected] http://mail.cs.uu.nl/mailman/listinfo/nix-commits
